design-token-library 0.1.0 → 0.3.0

package/dist/lib/library.js

@@ -1,6 +1,8 @@
+import { COMPUTED, RECIPE, isComputed } from "./recipe.js";
+import { REF, isRef } from "./ref.js";
 import { getNotifier } from "./notifier.js";
 import { Queue } from "./queue.js";
-import { empty } from "./utilities.js";
+import { empty, isToken } from "./utilities.js";
 import { Watcher } from "./watcher.js";
 /**
  * @public
@@ -11,168 +13,474 @@ export var Library;
      * @public
      */
     Library.create = (config) => {
+        // The runtime library is untyped; its shape is guaranteed by `config`.
         return LibraryImpl.create(config);
     };
 })(Library || (Library = {}));
+/**
+ * Thrown when reading a token whose value refers back to itself through
+ * one or more refs or computed values.
+ *
+ * @public
+ */
+export class CircularReferenceError extends Error {
+    name = "CircularReferenceError";
+    /**
+     * The names of the tokens in the cycle, starting and ending with the
+     * same token.
+     */
+    chain;
+    constructor(chain) {
+        super(`Circular reference: ${chain.join(" → ")}`);
+        this.chain = chain;
+    }
+}
+/**
+ * The changes to the configured values in a library's tokens: its own, and
+ * those of the libraries it extends, whose values it takes until its tokens
+ * are set.
+ */
+const configurationVersionOf = (scope) => {
+    let version = 0;
+    for (let s = scope; s; s = s.source) {
+        version += s.configurationVersion;
+    }
+    return version;
+};
+/**
+ * For a library's tokens, the tokens whose configured values refer to each,
+ * and the configuration it was made from.
+ */
+const dependentsIndexes = new WeakMap();
+/**
+ * The tokens currently resolving their values, outermost first.
+ */
+const resolving = [];
 const isObject = (value) => {
     return typeof value === "object" && value !== null;
 };
+const isGroup = (value) => {
+    return isObject(value) && !Array.isArray(value) && !isToken(value);
+};
+const GROUP_METADATA = [
+    "$type",
+    "$description",
+    "$extensions",
+    "$deprecated",
+];
 /**
- * @internal
+ * Names beginning with `$` are for format properties, except `$root`: the
+ * reserved name of a group's own token.
  */
-const isToken = (value) => {
-    return isObject(value) && "value" in value;
+const isChildKey = (key) => {
+    return !key.startsWith("$") || key === "$root";
 };
-const isGroup = (value) => {
-    return isObject(value) && !isToken(value);
+/**
+ * Records a group's own `$`-prefixed properties on it. They are not
+ * enumerable, so they never appear as children when a group is walked, and
+ * they let extending libraries resolve inherited types.
+ */
+const defineGroupMetadata = (group, ...sources) => {
+    for (const property of GROUP_METADATA) {
+        for (const source of sources) {
+            if (source[property] !== undefined) {
+                Reflect.defineProperty(group, property, {
+                    value: source[property],
+                });
+                break;
+            }
+        }
+    }
+};
+const defineToken = (library, key, get) => {
+    Reflect.defineProperty(library, key, {
+        get() {
+            const token = get();
+            // Token access is tracked because a ref reads its token from
+            // the library
+            Watcher.track(token);
+            return token;
+        },
+        enumerable: true,
+    });
 };
-const isAlias = (value) => {
-    return typeof value === "function";
+const createToken = (key, name, config, scope, typeContext, queue) => {
+    for (const property of Object.keys(config)) {
+        if (!property.startsWith("$")) {
+            throw new Error(`"${name}" has a $value, so it is a token and cannot have a child "${property}".`);
+        }
+    }
+    const { $value, $type, $description, $extensions, $deprecated } = config;
+    const resolvedType = $type || typeContext;
+    if (!resolvedType) {
+        throw new Error(`No '$type' found for token '${key}'. Types cannot be inferred, please add a $type to the token or to a group ancestor.`);
+    }
+    return new LibraryToken(name, $value, resolvedType, scope, $description || "", $extensions || {}, $deprecated ?? false, queue);
 };
-const recurseCreate = (name, library, config, context, typeContext, queue) => {
+const recurseCreate = (name, library, config, scope, typeContext, queue) => {
+    defineGroupMetadata(library, config);
+    typeContext = config.$type || typeContext;
     for (const key in config) {
-        if (key === "type") {
-            typeContext = config[key];
+        if (!isChildKey(key)) {
             continue;
         }
         const _name = name.length === 0 ? key : `${name}.${key}`;
         if (isGroup(config[key])) {
+            const group = {};
             Reflect.defineProperty(library, key, {
-                value: {},
+                value: group,
                 enumerable: true,
             });
-            recurseCreate(_name, library[key], config[key], context, config[key].type || typeContext, queue);
-            Object.freeze(library[key]);
+            recurseCreate(_name, group, config[key], scope, typeContext, queue);
+            Object.freeze(group);
         }
         else if (isToken(config[key])) {
-            const { value, type, description, extensions } = config[key];
-            if (!type && !typeContext) {
-                throw new Error(`No 'type' found for token '${key}'. Types cannot be inferred, please add a type to the token or to a group ancestor.`);
-            }
-            const token = new LibraryToken(_name, value, type || typeContext, context, description || "", extensions || {}, queue);
-            Reflect.defineProperty(library, key, {
-                get() {
-                    // Token access needs to be tracked because an alias token
-                    // is a function that returns a token
-                    Watcher.track(token);
-                    return token;
-                },
-                enumerable: true,
-            });
+            const token = createToken(key, _name, config[key], scope, typeContext, queue);
+            defineToken(library, key, () => token);
         }
     }
 };
-const recurseExtend = (name, sourceTokens, extendedTokens, config, // TODO allow new config options
-context, typeContext, queue) => {
-    const keys = new Set(Object.keys(sourceTokens).concat(Object.keys(config))); // Remove duplicate keys
+const recurseExtend = (name, sourceTokens, extendedTokens, config, scope, typeContext, queue, inherited) => {
+    // An extension can restate a group's type, or give one to a group that
+    // has none, but can't change it, as for a token.
+    const sourceType = Reflect.get(sourceTokens, "$type");
+    if (sourceType &&
+        config.$type !== undefined &&
+        config.$type !== sourceType) {
+        throw new Error(`An override cannot change the '$type' of group '${name}' from '${sourceType}' to '${config.$type}'.`);
+    }
+    const groupType = sourceType || config.$type;
+    defineGroupMetadata(extendedTokens, { $type: groupType }, 
+    // An extension may restate the group's other metadata.
+    { ...config, $type: undefined }, sourceTokens);
+    typeContext = groupType || typeContext;
+    const keys = new Set(Object.keys(sourceTokens)
+        .concat(Object.keys(config))
+        .filter(isChildKey)); // Remove duplicate keys
     for (const key of keys) {
-        const sourceHasKey = key in sourceTokens;
-        const configHasKey = key in config;
         const _name = name.length === 0 ? key : `${name}.${key}`;
-        const keyIsGroup = isGroup(sourceTokens[key]) || isGroup(config[key]);
-        const keyIsToken = isToken(sourceTokens[key]) || isToken(config[key]);
-        if (key === "type") {
-            typeContext = sourceTokens[key];
-            continue;
+        const source = Reflect.getOwnPropertyDescriptor(sourceTokens, key);
+        const configValue = config[key];
+        // A group of the source is a data property and a token an accessor,
+        // so telling them apart doesn't make the token of an extension.
+        if (source ? "value" in source : isGroup(configValue)) {
+            const group = {};
+            Reflect.defineProperty(extendedTokens, key, {
+                value: group,
+                enumerable: true,
+            });
+            if (source) {
+                recurseExtend(_name, source.value, group, configValue || {}, scope, typeContext, queue, inherited);
+            }
+            else {
+                recurseCreate(_name, group, configValue, scope, typeContext, queue);
+            }
+            Object.freeze(group);
         }
-        if (keyIsGroup) {
-            Reflect.defineProperty(extendedTokens, key, Object.create(sourceTokens[key]));
-            if (sourceHasKey) {
-                recurseExtend(_name, sourceTokens[key], extendedTokens[key], config[key] || {}, context, (sourceTokens.type || typeContext), queue);
+        else if (source) {
+            const token = new InheritedToken(() => untracked(() => sourceTokens[key]), scope, queue, configValue);
+            // A token the extension configures is made now, so its config
+            // is checked when the library is.
+            if (configValue !== undefined) {
+                token.get();
             }
-            else if (configHasKey) {
-                // This will always be the case
-                recurseCreate(_name, sourceTokens[key], extendedTokens[key], context, (sourceTokens.type || typeContext), queue);
+            if (configValue === undefined || !("$value" in configValue)) {
+                inherited.push(token);
             }
+            defineToken(extendedTokens, key, () => token.get());
         }
-        else if (keyIsToken) {
-            const token = sourceTokens[key] !== undefined
-                ? extendToken(sourceTokens[key], context, queue, config[key])
-                : new LibraryToken(_name, config[key].value, config[key].type || typeContext, context, config[key].description || "", config[key].extensions || {}, queue);
-            Reflect.defineProperty(extendedTokens, key, {
-                get() {
-                    // Token access needs to be tracked because an alias token
-                    // is a function that returns a token
-                    Watcher.track(token);
-                    return token;
-                },
-                enumerable: true,
-            });
+        else if (isToken(configValue)) {
+            const token = createToken(key, _name, configValue, scope, typeContext, queue);
+            defineToken(extendedTokens, key, () => token);
         }
     }
 };
-function extendToken(token, context, queue, value) {
+/**
+ * Reads without the read being tracked by the token that is resolving.
+ */
+const untracked = (read) => {
+    const stopWatching = Watcher.use({ watch() { } });
+    try {
+        return read();
+    }
+    finally {
+        stopWatching();
+    }
+};
+/**
+ * Unsubscribes the link of a collected {@link InheritedToken} from its
+ * source token.
+ */
+const links = new FinalizationRegistry((unlink) => unlink());
+/**
+ * The token of an extension for a token of the library it extends. It is
+ * made when it is first read, so an extension costs what it reads (#113).
+ *
+ * Until it is set, it has the value of its source token and follows its
+ * changes, through a link on the source token that holds it weakly: the
+ * library it extends doesn't keep an extension alive that nothing else
+ * refers to. It follows once it is made, or once its extension has a
+ * subscriber, which is told of a change to a token it hasn't read.
+ */
+class InheritedToken {
+    source;
+    scope;
+    queue;
+    node;
+    token = null;
+    unlink = null;
+    detached;
+    constructor(source, scope, queue, node) {
+        this.source = source;
+        this.scope = scope;
+        this.queue = queue;
+        this.node = node;
+        // An override has a value of its own.
+        this.detached = node !== undefined && "$value" in node;
+    }
+    get() {
+        if (this.token !== null) {
+            return this.token;
+        }
+        const token = extendToken(this.source(), this.scope, this.queue, this.node, this);
+        this.token = token;
+        this.follow();
+        return token;
+    }
+    follow() {
+        if (this.unlink !== null || this.detached) {
+            return;
+        }
+        // The link holds only a weak reference, so that the registry can
+        // collect this token, and nothing that refers to it.
+        const target = new WeakRef(this);
+        const notifier = getNotifier(this.source());
+        const link = {
+            onChange() {
+                target.deref()?.get().onChange();
+            },
+        };
+        const unlink = () => notifier.unsubscribe(link);
+        notifier.subscribe(link);
+        links.register(this, unlink, link);
+        this.unlink = () => {
+            unlink();
+            links.unregister(link);
+        };
+    }
+    /**
+     * Stops following the source token, when the token is set.
+     */
+    detach() {
+        this.unlink?.();
+        this.unlink = null;
+        this.detached = true;
+    }
+}
+function extendToken(token, scope, queue, node, inherited) {
+    if (node?.$type !== undefined && node.$type !== token.$type) {
+        throw new Error(`An override cannot change the '$type' of token '${token.name}' from '${token.$type}' to '${node.$type}'.`);
+    }
     const extendingToken = Object.create(token);
-    extendingToken.context = context;
+    extendingToken.scope = scope;
     extendingToken.cached = empty;
+    extendingToken.resolving = false;
+    extendingToken.notifying = false;
+    // Its own dependencies; sharing the source's set would let either token
+    // drop the other's subscriptions.
+    extendingToken.subscriptions = new Set();
+    extendingToken.previousSubscriptions = null;
     extendingToken.watchContext = extendingToken;
     extendingToken.queue = queue;
-    if (value !== undefined) {
-        extendingToken.raw = value;
+    // An extension can restate the token's metadata along with its value.
+    if (node?.$description !== undefined) {
+        extendingToken._description = node.$description;
+    }
+    // A new object, so mutating it can't leak to the source or the override.
+    extendingToken._extensions = { ...token.$extensions, ...node?.$extensions };
+    if (node?.$deprecated !== undefined) {
+        extendingToken._deprecated = node.$deprecated;
+    }
+    if (node !== undefined && "$value" in node) {
+        extendingToken.raw = node.$value;
     }
     else {
-        // Subscribe to changes
-        // spy on set, unsubscribe when set
-        const subscriber = {
-            onChange() {
-                extendingToken.onChange();
-            },
-        };
-        // token.value;
-        getNotifier(token).subscribe(subscriber);
-        const set = extendingToken.set;
+        // Not extendingToken.set: when the extended token is an extension
+        // that hasn't been set, that is the extended token's own wrapper,
+        // which sets the extended token.
+        const set = LibraryToken.prototype.set;
         extendingToken.set = (value) => {
-            getNotifier(token).unsubscribe(subscriber);
+            inherited.detach();
+            // Own the inherited value, so set() detaches even when the
+            // new value is identical and doesn't notify.
+            extendingToken.raw = extendingToken.raw;
             set.call(extendingToken, value);
             extendingToken.set = set;
         };
     }
     return extendingToken;
 }
-const recurseResolve = (value, context) => {
-    const r = Array.isArray(value) ? [] : {};
-    for (const key in value) {
-        let v = value[key];
-        if (isAlias(v)) {
-            v = v(context);
+/**
+ * The number of links in an object's prototype chain.
+ */
+const prototypeDepth = (value) => {
+    let depth = 0;
+    for (let prototype = Object.getPrototypeOf(value); prototype !== null; prototype = Object.getPrototypeOf(prototype)) {
+        depth++;
+    }
+    return depth;
+};
+/**
+ * Tests whether an object is plain data, which may hold refs: an array that
+ * isn't a subclass of `Array`, or an object whose prototype chain has at most
+ * one link, such as an object literal from any realm or `Object.create(null)`.
+ * Any other object, such as a class instance, a `Date` or a `Map`, is a value
+ * as it is.
+ */
+const isPlain = (value) => {
+    return Array.isArray(value)
+        ? prototypeDepth(value) === 2
+        : prototypeDepth(value) <= 1;
+};
+/**
+ * The token at a path of a library. Each group and the token are read from
+ * the library, so the token that reads it depends on it.
+ */
+const tokenAt = (tokens, path) => {
+    let node = tokens;
+    for (const key of path) {
+        node = isObject(node) ? Reflect.get(node, key) : undefined;
+    }
+    if (!(node instanceof LibraryToken)) {
+        throw new Error(`The library has no token "${path.join(".")}".`);
+    }
+    return node;
+};
+/**
+ * Resolves a value in a library's scope. A ref is replaced by its token's
+ * value, as it is: the value is resolved and frozen already, so it isn't
+ * copied again. A computed value is replaced by the result of its recipe's
+ * function, or of the function that overrides it in the scope, called with
+ * its arguments resolved. Plain data is copied from its own properties, including
+ * symbol-keyed and non-enumerable ones, with its refs resolved, and the copy
+ * is frozen, so the config isn't. A getter is read once, into a data
+ * property. An object that is in the value twice, or in itself, has one copy.
+ * Anything else, such as a class instance or a function, is returned as it
+ * is: it can't be rebuilt, so it isn't copied, searched or frozen.
+ */
+const resolve = (value, scope) => {
+    const copies = new Map();
+    const walk = (value) => {
+        if (!isObject(value)) {
+            return value;
         }
-        if (isToken(v)) {
-            v = v.value;
+        if (isRef(value)) {
+            return tokenAt(scope.tokens, value[REF]).$value;
         }
-        if (isObject(v)) {
-            r[key] = recurseResolve(v, context);
+        if (isComputed(value)) {
+            const { recipe, args } = value[COMPUTED];
+            const fn = scope.recipes.get(recipe) ?? recipe[RECIPE].fn;
+            return walk(fn(...args.map(walk)));
         }
-        else {
-            r[key] = v;
+        if (copies.has(value)) {
+            return copies.get(value);
         }
+        if (!isPlain(value)) {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            const copy = new Array(value.length);
+            copies.set(value, copy);
+            for (let i = 0; i < value.length; i++) {
+                copy[i] = walk(value[i]);
+            }
+            return Object.freeze(copy);
+        }
+        const copy = Object.create(Object.getPrototypeOf(value));
+        copies.set(value, copy);
+        for (const key of Reflect.ownKeys(value)) {
+            const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+            Reflect.defineProperty(copy, key, "value" in descriptor
+                ? { ...descriptor, value: walk(descriptor.value) }
+                : {
+                    value: walk(Reflect.get(value, key)),
+                    enumerable: descriptor.enumerable,
+                    writable: true,
+                    configurable: true,
+                });
+        }
+        return Object.freeze(copy);
+    };
+    return walk(value);
+};
+const assertNoRoot = (config) => {
+    if ("$root" in config) {
+        throw new Error(`"$root" is the token of a group, so it cannot be at the top level of a library.`);
     }
-    return r;
 };
+/**
+ * The runtime library. It is untyped internally; {@link Library.create}
+ * exposes it through the typed {@link (Library:namespace).Library} interface.
+ */
 class LibraryImpl {
-    tokens;
+    scope;
     queue;
-    constructor(tokens, queue) {
-        this.tokens = tokens;
+    tokens;
+    /**
+     * The inherited tokens of an extension. Each follows its source token
+     * once it is read, and all of them once the library has a subscriber,
+     * after which this is null.
+     */
+    inherited;
+    constructor(scope, queue, inherited = []) {
+        this.scope = scope;
         this.queue = queue;
+        this.tokens = scope.tokens;
+        this.inherited = inherited;
+        // Groups are frozen as they are built; the root is frozen here.
+        Object.freeze(this.tokens);
     }
     subscribe(subscriber) {
+        // A subscriber is told of a change to a token of the source that the
+        // extension hasn't read.
+        if (this.inherited !== null) {
+            for (const token of this.inherited) {
+                token.follow();
+            }
+            this.inherited = null;
+        }
         this.queue.subscribe(subscriber);
     }
     unsubscribe(subscriber) {
         this.queue.unsubscribe(subscriber);
     }
-    extend(config) {
-        // TODO should not type Library.Config<any>
+    extend(config, options = {}) {
+        assertNoRoot(config);
         const queue = new Queue();
-        const tokens = {};
-        recurseExtend("", this.tokens, tokens, config, tokens, null, queue);
-        return new LibraryImpl(tokens, queue);
+        const recipes = new Map(this.scope.recipes);
+        for (const { recipe, fn } of options.recipes ?? []) {
+            recipes.set(recipe, fn);
+        }
+        const scope = {
+            tokens: {},
+            recipes,
+            configurationVersion: 0,
+            source: this.scope,
+        };
+        const inherited = [];
+        recurseExtend("", this.tokens, scope.tokens, config, scope, null, queue, inherited);
+        return new LibraryImpl(scope, queue, inherited);
     }
     static create(config) {
+        assertNoRoot(config);
         const queue = new Queue();
-        const tokens = {};
-        recurseCreate("", tokens, config, tokens, null, queue);
-        return new LibraryImpl(tokens, queue);
+        const scope = {
+            tokens: {},
+            recipes: new Map(),
+            configurationVersion: 0,
+        };
+        recurseCreate("", scope.tokens, config, scope, null, queue);
+        return new LibraryImpl(scope, queue);
     }
 }
 /**
@@ -181,72 +489,334 @@ class LibraryImpl {
 class LibraryToken {
     name;
     _type;
-    context;
+    scope;
     _description;
-    _extensions;
+    _deprecated;
     queue;
     raw;
     cached = empty;
+    resolving = false;
+    notifying = false;
     subscriptions = new Set();
-    constructor(name, value, _type, context, _description, _extensions, queue) {
+    /**
+     * While resolving, the subscriptions from the previous resolution. Sources
+     * watched again keep their subscription instead of re-subscribing.
+     */
+    previousSubscriptions = null;
+    _extensions;
+    constructor(name, value, _type, scope, _description, extensions, _deprecated, queue) {
         this.name = name;
         this._type = _type;
-        this.context = context;
+        this.scope = scope;
         this._description = _description;
-        this._extensions = _extensions;
+        this._deprecated = _deprecated;
         this.queue = queue;
         this.raw = value;
-        this.context = context;
+        // A copy, so changing the config's top-level keys can't change the token.
+        this._extensions = { ...extensions };
+    }
+    get $deprecated() {
+        return this._deprecated;
     }
-    get type() {
+    get $type() {
         return this._type;
     }
-    get description() {
+    get $description() {
         return this._description;
     }
-    get extensions() {
+    get $extensions() {
         return this._extensions;
     }
     /**
      * Gets the token value
      */
-    get value() {
+    get $value() {
         if (this.cached !== empty) {
             return this.cached;
         }
-        this.disconnect();
+        if (this.resolving) {
+            const chain = resolving
+                .slice(resolving.indexOf(this))
+                .map((token) => token.name);
+            throw new CircularReferenceError([...chain, this.name]);
+        }
+        const previous = this.subscriptions;
+        this.previousSubscriptions = previous;
+        this.subscriptions = new Set();
+        this.resolving = true;
+        resolving.push(this);
         const stopWatching = Watcher.use(this);
-        const raw = isAlias(this.raw) ? this.raw(this.context) : this.raw;
-        const normalized = isToken(raw) ? raw.value : raw;
-        const value = isObject(normalized)
-            ? recurseResolve(normalized, this.context)
-            : normalized;
-        this.cached = value;
-        stopWatching();
-        return value;
+        try {
+            // The config's types guarantee what the raw value resolves to.
+            const value = resolve(this.raw, this.scope);
+            this.cached = value;
+            return value;
+        }
+        finally {
+            this.resolving = false;
+            resolving.pop();
+            stopWatching();
+            this.previousSubscriptions = null;
+            // Unsubscribe from sources that were not watched this time.
+            for (const notifier of previous) {
+                if (!this.subscriptions.has(notifier)) {
+                    notifier.unsubscribe(this);
+                }
+            }
+        }
+    }
+    toString() {
+        return JSON.stringify({
+            name: this.name,
+            $type: this.$type,
+            $value: this.$value,
+            $description: this.$description,
+            $extensions: this.$extensions,
+            $deprecated: this.$deprecated,
+        });
     }
     set(value) {
+        if (Object.is(this.raw, value)) {
+            return;
+        }
         this.raw = value;
+        this.scope.configurationVersion++;
         this.onChange();
     }
     onChange() {
-        this.queue.add(this);
-        this.cached = empty;
-        getNotifier(this).notify();
+        // A circular reference that threw while resolving still leaves the
+        // tokens subscribed to each other, so don't notify re-entrantly.
+        if (this.notifying) {
+            return;
+        }
+        this.notifying = true;
+        try {
+            this.queue.add(this);
+            this.cached = empty;
+            getNotifier(this).notify();
+        }
+        finally {
+            this.notifying = false;
+        }
     }
     watch(source) {
         const notifier = getNotifier(source);
-        notifier.subscribe(this);
+        if (this.subscriptions.has(notifier)) {
+            return;
+        }
         this.subscriptions.add(notifier);
+        if (!this.previousSubscriptions?.has(notifier)) {
+            notifier.subscribe(this);
+        }
     }
     /**
-     * Disconnect the token from it's subscriptions
+     * The value a token was configured or last set with. An extension's
+     * token that has no value of its own inherits its source's.
      */
-    disconnect() {
-        for (const record of this.subscriptions.values()) {
-            record.unsubscribe(this);
-            this.subscriptions.delete(record);
+    static configuredValue(token) {
+        return token.raw;
+    }
+    /**
+     * The tokens that the refs in a token's configured value are to, in the
+     * token's library, searched as {@link resolve} resolves them: in plain
+     * data and in the arguments of computed values.
+     */
+    static dependencies(token) {
+        const dependencies = new Set();
+        const seen = new Set();
+        const walk = (value) => {
+            if (!isObject(value) || seen.has(value)) {
+                return;
+            }
+            seen.add(value);
+            if (isRef(value)) {
+                dependencies.add(tokenAt(token.scope.tokens, value[REF]));
+            }
+            else if (isComputed(value)) {
+                value[COMPUTED].args.forEach(walk);
+            }
+            else if (isPlain(value)) {
+                for (const key of Reflect.ownKeys(value)) {
+                    walk(Reflect.get(value, key));
+                }
+            }
+        };
+        walk(token.raw);
+        return dependencies;
+    }
+    /**
+     * The tokens of the token's library whose configured values refer to it.
+     * The index is made from the library's tokens once, and again after a
+     * token is set to a different value.
+     */
+    static dependents(token) {
+        const version = configurationVersionOf(token.scope);
+        let index = dependentsIndexes.get(token.scope);
+        if (index?.version !== version) {
+            const dependents = new Map();
+            for (const entry of walkEntries(token.scope.tokens, [], {
+                whatToShow: "token",
+            })) {
+                const dependent = libraryTokenOf(entry.token);
+                for (const dependency of LibraryToken.dependencies(dependent)) {
+                    const list = dependents.get(dependency);
+                    if (list) {
+                        list.push(dependent);
+                    }
+                    else {
+                        dependents.set(dependency, [dependent]);
+                    }
+                }
+            }
+            index = { version, dependents };
+            dependentsIndexes.set(token.scope, index);
         }
+        return index.dependents.get(token) ?? [];
     }
 }
+const libraryTokenOf = (token) => {
+    if (!(token instanceof LibraryToken)) {
+        throw new Error(`"${token.name}" is not a token of a library.`);
+    }
+    return token;
+};
+/**
+ * A token's value as it was configured, or last given to `set()`, with its
+ * refs and computed values unresolved. A token of a library made by
+ * `extend()` that isn't given a value has its source token's.
+ *
+ * @remarks
+ * A token's `$value` is resolved, so it can't tell a value that is given from
+ * one that is derived from other tokens, or say where in a value a ref is. A
+ * tool that reads how a library is configured finds the refs in this value
+ * with {@link isRef} and the computed values with {@link isComputed}: a value
+ * with neither, at any depth, is given. A converter that writes a ref as a
+ * CSS `var()`, rather than its token's value, reads the ref here and its
+ * path with {@link pathOf}.
+ *
+ * It's the value the token holds, not a copy, so it isn't frozen. Changing it
+ * doesn't change the token: give a new value to `set()`. Refs and computed
+ * values are searched for in plain data, as the library resolves them, and
+ * not in a class instance or a function.
+ *
+ * @example
+ * ```ts
+ * const isGiven = (value: unknown): boolean =>
+ *     !isRef(value) &&
+ *     !isComputed(value) &&
+ *     (typeof value !== "object" || value === null ||
+ *         Object.values(value).every(isGiven));
+ *
+ * isGiven(configuredValueOf(library.tokens.colors.primary)); // true
+ * isGiven(configuredValueOf(library.tokens.colors.hover)); // false: a recipe
+ * ```
+ *
+ * @public
+ */
+export const configuredValueOf = (token) => LibraryToken.configuredValue(libraryTokenOf(token));
+/**
+ * The tokens that a token's value refers to, through refs anywhere in its
+ * configured value, including the arguments of the recipes it's computed
+ * with, in the token's library. Each token is listed once, in the order its
+ * first ref is in the value.
+ *
+ * @remarks
+ * These are the tokens the value is made from, and not theirs in turn: a
+ * tool follows each with `dependenciesOf()` for the whole chain. A value
+ * computed by a recipe from literal arguments only has no dependencies,
+ * though it's derived: {@link configuredValueOf} tells that apart.
+ *
+ * It throws when a ref's path isn't a token of the library, as reading the
+ * token's `$value` does.
+ *
+ * @example
+ * ```ts
+ * // hover: { $value: Recipes.darken(theme.colors.primary, 0.2) }
+ * dependenciesOf(library.tokens.colors.hover).map((token) => token.name);
+ * // ["colors.primary"]
+ * ```
+ *
+ * @public
+ */
+export const dependenciesOf = (token) => 
+// The token at a ref's path is a token of the library, of shape `R`: the
+// config's types guarantee it.
+Object.freeze([
+    ...LibraryToken.dependencies(libraryTokenOf(token)),
+]);
+export function entriesOf(library, options = {}) {
+    return walkEntries(library.tokens, [], options);
+}
+function* walkEntries(node, path, options) {
+    const { whatToShow = "all", filter } = options;
+    for (const key of Object.keys(node)) {
+        if (!isChildKey(key)) {
+            continue;
+        }
+        const child = node[key];
+        const childPath = [...path, key];
+        const entry = isToken(child)
+            ? { kind: "token", path: childPath, token: child }
+            : { kind: "group", path: childPath, group: child };
+        let result = true;
+        if (whatToShow === "all" || whatToShow === entry.kind) {
+            result = filter?.(entry) ?? true;
+            if (result === true) {
+                yield entry;
+            }
+        }
+        if (entry.kind === "group" && result !== "reject") {
+            yield* walkEntries(child, childPath, options);
+        }
+    }
+}
+/**
+ * The tokens whose values refer to a token, through refs anywhere in their
+ * configured values, including the arguments of their recipes, in the
+ * token's library. It is the reverse of {@link dependenciesOf}: each token is
+ * listed once, in the order of the library.
+ *
+ * @remarks
+ * These are the tokens that refer to the token directly. A token whose value
+ * may change when this one is set is also one that refers to one of those: a
+ * tool follows each with `dependentsOf()` for the whole set, as it follows
+ * {@link dependenciesOf} for the chain the other way.
+ *
+ * This reads the configured values and not the values, so it resolves no
+ * token, and so it is known of a library whose tokens have not been read. It
+ * is found for the whole library once and kept until a token is set to a
+ * different value, so each call after the first is a lookup. A value a recipe
+ * reads other than through its arguments is not seen, as for
+ * {@link dependenciesOf}.
+ *
+ * It throws when a ref in a token of the library isn't a token of it, as
+ * reading the token's `$value` does.
+ *
+ * @example
+ * ```ts
+ * // hover: { $value: Recipes.darken(theme.colors.primary, 0.2) }
+ * dependentsOf(library.tokens.colors.primary).map((token) => token.name);
+ * // ["colors.hover"]
+ *
+ * // Every token that may change when a token is set
+ * const affected = new Set<Library.Token<any, any>>();
+ * const visit = (token: Library.Token<any, any>) => {
+ *     for (const dependent of dependentsOf(token)) {
+ *         if (!affected.has(dependent)) {
+ *             affected.add(dependent);
+ *             visit(dependent);
+ *         }
+ *     }
+ * };
+ * visit(extension.tokens.color.context);
+ * ```
+ *
+ * @public
+ */
+export const dependentsOf = (token) => 
+// The tokens that refer to a token are of its library, of shape `R`: the
+// config's types guarantee it.
+Object.freeze([
+    ...LibraryToken.dependents(libraryTokenOf(token)),
+]);
 //# sourceMappingURL=library.js.map