Should handling nullish values and null-prototype objects be the focus?

[mfulton26]

An extensions syntax may not be necessary if nullish values and null-prototype objects do not need to be handled or if something is made for handling them.

e.g. Symbols can be used to implement code similar to that in the example in README.md:

function x(attributes) {
    const key = Symbol()
    Object.defineProperty(Object.prototype, key, attributes)
    return key
}

// define two extension methods
const toArray = x({ value() { return [...this] } })
const toSet = x({ value() { return new Set(this) } })

// define a extension accessor
const allDivs = x({ get() { return this.querySelectorAll('div') } })

// reuse built-in prototype methods and accessors
const flatMap = x({ value: Array.prototype.flatMap })
const size = x(Object.getOwnPropertyDescriptor(Set.prototype, 'size'))

// Use extension methods and accessors to calculate
// the count of all classes of div element.
let classCount = document[allDivs]
	[flatMap](e => e.classList[toArray]())
	[toSet]()[size]

Symbol-keyed prototype augmentation does not suffer from the same problems as string-keyed prototype augmentation because symbols, unlike strings, are unique at runtime and will not conflicts with other augmentations nor future built-in definitions.

Using symbols here doesn't work for null or undefined (although nullish coalescing does work) nor does it work with null-prototype objects. That may be sufficient. If not, then perhaps a proposal focusing on handling those edge cases would be worthwhile.

Ideas: A global/root prototype that can only contain non-enumerable definitions using symbol keys.

function x(attributes) {
    const key = Symbol()
    Object.defineProperty(GlobalPrototype, key, attributes)
    return key
}

[ljharb]

This is only true of non-registered symbols, and since regardless they can be obtained by reflection, as well as be getters, they share the majority of the same problems as strings.

[ewinslow]

Clever :). Another way to frame your idea is:

1. An extensions syntax can work with receivers that don't inherit from Object (null prototype, etc)
2. An extensions syntax can be written to not have any side effects, nor require monkey patching prototypes, making the code more tree shakable.
3. An extensions syntax saves us an extra symbol allocation per function.
4. An extension syntax can make call sites nicer by avoiding bracket syntax.
5. An extension syntax can make call sites faster by avoiding property lookup.

I do always find it a valuable exercise to see how far we can get using existing syntax creatively.

[hax]

@mfulton26 Yeah this is a clever trick.
Actually I recall that I have seen similar trick many years ago, but at that time I didn't realize such trick is already friendly to tree-shaking and current bundlers could already support it well (by declaring x as sideeffect free)!

if nullish values and null-prototype objects do not need to be handled

I think nullish values is not important (normal methods also don't deal with them at all), though null-prototype objects is a real problem. Another issue is any access always need to visit the whole prototype chain (though jit engines can optimize it). So I think it's better to have dedicated extension syntax.

I do always find it a valuable exercise to see how far we can get using existing syntax creatively.

Totally agree!

[ewinslow]

Heh that's an interesting idea: just lie to the bundlers and declare the helper function to be side-effect free!

Another potential issue: this sort of access pattern is syntactically indistinguishable from o[expr] in which case expr could evaluate to anything, not just a particular symbol. I believe closure compiler treats this as a reflection access and therefore deoptimizes all other properties on the class, because it could refer to any of them. @shicks to check me on this.

Also good point about having to walk prototype chain all the way to Object.

Another q: how is typescript supposed to type this? Can we know the shape of the method associated with that particular symbol?

[hax]

Another q: how is typescript supposed to type this? Can we know the shape of the method associated with that particular symbol
@ewinslow

I think it's impossible in current TS, for example, you can only get unique symbol with explicit const s = Symbol() which means x() can never create unique symbol in plain ts code.

A workaround is using some compiler plugin, which transform code:

/** @extension-method */
export function Last<T>(this: Array<T>) {
    return this[this.length - 1]
}

to

export const Last = Symbol()
function _Last<T>(this: Array<T>) {
    return this[this.length - 1]
}
Object.prototype[Last] = _Last
declare global {
    interface Object {
        [Last]: typeof _Last
    }
}

Then you can write type-safely:

import {Last} from "array-extension"
let a = [1,2,3]
let value = a[Last]()

[ljharb]

function x() { return Symbol() } would mean that x() creates a unique symbol, no?

[ewinslow]

TS (currently) complains:

function x(): unique symbol {
              ^^^^^^^^^^^^^ 'unique symbol' types are not allowed here.
  return Symbol();
}

[ljharb]

I believe unique is a typescript-specific thing (nominal typing) and isn't related to symbols in JS. : symbol would be the return type of x. "unique symbol" in a JS context is "a non-registered symbol".

[mfulton26]

The only way I know of to do this in TypeScript is to declare each unique symbol separately and explicitly use them when augmenting prototypes. The larger problem IMO in TS is that augmenting the TypeScript types from libraries is tedious and isn't inferred automatically in any way.

function x<K extends symbol>(symbol: K, attributes: Parameters<typeof Object.defineProperty>[2]) {
    Object.defineProperty(Object.prototype, symbol, attributes);
    return symbol;
}

// define two extension methods
const toArray = Symbol();
x(toArray, { value() { return [...this] } })
declare global {
    interface DOMTokenList {
        [toArray](): string[];
    }
}
const toSet = Symbol();
x(toSet, { value() { return new Set(this) } })
declare global {
    interface Array<T> {
        [toSet](): Set<T>;
    }
}

// define a extension accessor
const allDivs = Symbol();
x(allDivs, { get() { return this.querySelectorAll('div') } })
declare global {
    interface Document {
        [allDivs]: NodeListOf<HTMLDivElement>;
    }
}

// reuse built-in prototype methods and accessors
const flatMap = Symbol();
x(flatMap, { value: Array.prototype.flatMap })
declare global {
    interface NodeListOf<TNode extends Node> {
        [flatMap]<U>(callback: (value: TNode) => U | ReadonlyArray<U>): U[];
    }
}
const size = Symbol();
x(size, Object.getOwnPropertyDescriptor(Set.prototype, 'size')!)
declare global {
    interface Set<T> {
        [size]: number;
    }
}

// Use extension methods and accessors to calculate
// the count of all classes of div element.
let classCount = document[allDivs]
	[flatMap](e => e.classList[toArray]())
	[toSet]()[size]

I haven't used it much for anything (yet) but I did create a little library based on these ideas but to make doing any side-effect or transform/pipe doable via chaining: https://github.com/mfulton26/scope-methods. It works well but, at least in TypeScript 5, the code completion didn't work well with symbol-keyed properties. I believe that is improving though with TypeScript 6–7.