symbola/symbola

Native JavaScript prototype extension with symbol protocols

Symbola is a proof-of-concept library for 🤯 extending the native JavaScript prototypes 🤯 with methods identified by symbols to prevent naming collisions, which enables method chaining syntax without having to wrap or convert the target. For example, Map and Set objects don't have built-in iteration methods, so iterating over them requires a conversion to an array:

const xs = new Set([1, 2, 3, 4])
// Converting to array with ... spread syntax to chain map and filter
const ys = [...xs].map((x) => x + 1).filter((x) => x % 2)

In comparison, extending the native prototypes allows to use iteration methods on iterables without conversion:

// Importing the unique symbols used to access iteration methods
import { map, filter } from '@symbola/iterable'

const xs = new Set([1, 2, 3, 4])
// Calling [map] and [filter] methods without conversion
const ys = xs[map]((x) => x + 1)[filter]((x) => x % 2)

⭐ Try Symbola in an interactive sandbox
📖 Article exploring symbol protocol extensions in more depth

Rationale for symbol protocol extensions

The key difference when extending native prototypes with symbols as keys is that symbol primitives are unique, so there is no practical chance of repeating situations like SmooshGate, where a non-standard Array.prototype.flatten method prevented a standard method with the same name from being added. The trade off is that accessing methods with symbols requires the [] operator instead of the ., but it's a small difference compared to overcoming the limitations of method chaining that are well documented in, for example, the pipeline operator proposal. In short, extending native prototoypes is a workaround for making fluent interfaces more widely applicable without the downsides of other workarounds like temporary variables or wrappers like _.chain.

Similar features in other languages

A number of other languages have ad-hoc extension features like trait composition or protocol extensions, which allow to retroactively extend types without modifying their definition based on conformity to a specific blueprint, contract, convention or protocol. For example, JavaScript defines iteration protocols, which are a set of requirements for types to be iterable, which means returning an associated iterator type when the [Symbol.iterator]() method is called, which in turn implements methods to return iteration results. Conforming to the iteration protocols means that the type is supported by for-of loop syntax or yield or yield* operators in generator functions, and is also supported by third-party utility libraries like IxJS or iterall, but these libraries have generally had limited adoption because of the limitations of chaining syntax in JavaScript, where retroactively extending types with chainable methods requires using wrappers, or to extend the native prototypes as in the iteration helpers proposal, which means going through an exceedingly long standardization process.

Symbol protocol extensions are a userland workaround for the typical limitations of avoiding a nested coding style in JavaScript, and it uses the language's flexibility to implement something similar to Rust traits, Swift protocols or Haskell typeclasses, and an additional advantage over, for example, the proposed standard extensions to native prototypes is that symbol protocols work for all objects that implement them, not just those inheriting from specific intrinsics like %Iterator.prototype%.

Type safety

TypeScript allows constraining methods to just receivers that conform to a specific protocol, so symbol protocol methods are typed to prevent being used with non-conforming types like so:

{
  [filter]()<A>(this: Iterable<A>, fn: (a: A) => boolean) { ... }
}

The actual implementation for the symbol protocols also does not rely on anything magical and just add the methods to the native prototypes and use declaration merging to make TypeScript recognize the added methods.

Full implementation for the filterable protocol

import { extend } from '@symbola/core'

export const filter = Symbol('filter')

export default abstract class Filterable {
  *[filter]<T>(this: Iterable<T>, callback: (value: T) => boolean) {
    for (const value of this) {
      if (callback(value)) {
        yield value
      }
    }
  }
}

declare global {
  interface Object extends Filterable {}
}

extend(Object.prototype, Filterable.prototype)

Standard ad-hoc extension proposal

Aside from the |> pipeline operator proposal, there is also the :: bind operator proposal that addresses the same issue of ad-hoc extension of existing types, and there is also a stage-1 extensions proposal based on the same operator, which would essentially do the same as is currently already possible in userland with symbol protocol extensions.

Example use cases

Lazy iteration

The symbol methods are added to Object.prototype, so they work on any object that implements the JavaScript iteration protocols, including generators:

import { filter } from '@symbola/iterable'

function* naturals() {
  let i = 1
  while (true) {
    yield i++
  }
}
const xs = naturals()[filter]((x) => x % 2)

The above example doesn't get stuck in an infinite loop because it takes advantage of the laziness of iterators, which is not possible when converting iterators to arrays, because the array iteration methods are eager.

The @symbola/iterable package implements the methods from the iterator helpers proposal meant to support lazy iteration.

Logging

[log]() calls can be inserted in the code without having to wrap the target:

import { log } from '@symbola/core'

const foo = bar[log]().baz().qux()

Set methods

The @symbola/set package implements the proposed method extensions from the Set methods proposal.

Example

import { difference } from '@symbola/set'

const a = new Set([1, 2, 3, 4])
const b = new Set([3, 4, 5, 6])

a[difference](b) // -> Set([3, 4])

Usage

The library is divided into separate packages:

• @symbola/core
• @symbola/iterable
• @symbola/async-iterable
• @symbola/object
• @symbola/function
• @symbola/number
• @symbola/set

Importing the specific package will extend the corresponding native prototypes.

Caveats

JavaScript symbols provide only weak encapsulation or privacy, so it's possible for code that uses Reflect.ownKeys on native prototypes to conflict with the custom symbol properties, but the practical chances of it are exceedingly low.

The symbol properties also won't work on objects that don't inherit from Object.prototype, like those created with Object.create(null) or null or undefined values.

Alternatives

• iter-tools
• IxJS