design-token-library 0.1.0 → 0.2.0

package/dist/lib/library.d.ts

@@ -1,80 +1,407 @@
+import { COMPUTED, RECIPE } from "./recipe.js";
+import { REF } from "./ref.js";
 import { DesignToken } from "./design-token.js";
-import { DeepPartial } from "./utilities.js";
+/**
+ * The key of the phantom type of a ref: what it resolves to, in a library of
+ * what shape. It's never set.
+ */
+declare const RESOLVES: unique symbol;
+/**
+ * The key of the phantom type of a computed value, apart from a ref's, so
+ * that a ref's type is never inferred from a computed value's.
+ */
+declare const COMPUTES: unique symbol;
+/**
+ * The key of the phantom type that marks a token in
+ * {@link (Library:namespace).TokenValues}. It's never set.
+ */
+declare const TOKEN: unique symbol;
 /**
  * @public
  */
 export declare namespace Library {
-    interface Library<T extends {}, R extends {} = T> {
+    export interface Library<T extends {}, R extends {} = T> {
         tokens: TokenLibrary<T, R>;
         subscribe(subscriber: Library.Subscriber<R>): void;
         unsubscribe(subscriber: Library.Subscriber<R>): void;
-        extend<K extends {} = any>(config: DeepPartial<T> & Config<K, R & K>): Library<T & K, R & K>;
+        /**
+         * Creates a library with the values of the tokens replaced, and
+         * recipes overridden.
+         *
+         * @remarks
+         * This has no tokens to add, so a value is checked against the type
+         * of its token wherever the token is.
+         */
+        extend(config: ExtendConfig<T, R>, options?: ExtendOptions): Library<T, R>;
+        /**
+         * Creates a library with the values of tokens replaced, new tokens,
+         * and recipes overridden.
+         */
+        extend<K extends NoRoot<K> = {}>(config: ExtendConfig<T, R & NewTokens<K, T>> & Config<K, R & NewTokens<K, T>, never, T> & NoInfer<ConfigValueCheck<K, R & NewTokens<K, T>>> & (ConfigTypeHint | {}), options?: ExtendOptions): Library<T & NewTokens<K, T>, R & NewTokens<K, T>>;
     }
-    interface Subscriber<R extends {}> {
-        onChange(records: ReadonlyArray<Library.Token<DesignToken.Any, R>>): void;
+    /**
+     * The tokens and groups of `K` that are new relative to a source library
+     * of shape `T`. Overrides of tokens in `T` are removed so that they keep
+     * the source token's type.
+     *
+     * @public
+     */
+    export type NewTokens<K, T> = {
+        [P in keyof K as P extends keyof T ? T[P] extends DesignToken.Shape ? never : P : P]: P extends keyof T ? NewTokens<K[P], T[P]> : K[P];
+    };
+    /**
+     * `$root` is the token of a group, so a library cannot have one at its top
+     * level, where there is no group to name it for.
+     *
+     * @public
+     */
+    export type NoRoot<T> = {
+        [K in keyof T]: K extends "$root" ? never : T[K];
+    };
+    export interface Subscriber<R extends {}> {
+        onChange(records: ReadonlyArray<Library.TokenRecord<R>>): void;
     }
+    /**
+     * A union of all tokens in a library of shape `T`.
+     *
+     * @public
+     */
+    export type TokensOf<T> = {
+        [K in keyof T]-?: T[K] extends DesignToken.Shape ? T[K] : K extends keyof DesignToken.Group ? never : T[K] extends object ? TokensOf<T[K]> : never;
+    }[keyof T];
+    /**
+     * A {@link (Library:namespace).Token} of any token in a library of shape `R`.
+     * The union is discriminated by `type`.
+     *
+     * @public
+     */
+    export type TokenRecord<R extends {}> = TokensOf<R> extends infer T ? T extends DesignToken.Shape ? Token<T, R> : never : never;
     /**
      * Defines a token library that can be interacted with
      * to mutate token values.
      *
+     * @remarks
+     * `G` is the type inherited from ancestor groups.
+     *
+     * @public
+     */
+    export type TokenLibrary<T extends {}, R extends {} = T, G extends string = never> = TokenGroup<T, R, GroupType<T, G>>;
+    type TokenGroup<T extends {}, R extends {}, G extends string> = {
+        [K in keyof Readonly<T>]: T[K] extends DesignToken.Shape ? Token<T[K], R, G> : K extends keyof DesignToken.Group ? T[K] : T[K] extends {} ? TokenLibrary<T[K], R, G> : never;
+    };
+    /**
+     * The value type of each token of a library of shape `T`, by its path.
+     * Refs and computed values are typed by it, so they're given only to a
+     * library that has their tokens, with values of the same types, whether
+     * its shape is declared or inferred from its config.
+     *
+     * @public
+     */
+    export type TokenValues<T> = {
+        [K in keyof T as K extends keyof DesignToken.Group ? never : K]: T[K] extends DesignToken.Shape ? TokenValue<DesignToken.ValueByToken<T[K]>> : T[K] extends object ? TokenValues<T[K]> : never;
+    };
+    /**
+     * A token with a value of type `V`, in
+     * {@link (Library:namespace).TokenValues}. It's only a type: it marks
+     * where a path ends at a token rather than going into its value.
+     *
+     * @public
+     */
+    export interface TokenValue<V> {
+        readonly [TOKEN]: V;
+    }
+    /**
+     * The dotted path of each token in `T`, the
+     * {@link (Library:namespace).TokenValues} of a library, whose value is a
+     * `V`. These are the paths {@link ref} takes where a `V` is expected.
+     *
+     * @public
+     */
+    export type TokenPath<T, V> = {
+        [K in keyof T & string]: T[K] extends TokenValue<infer W> ? [W] extends [V] ? K : never : `${K}.${TokenPath<T[K], V>}`;
+    }[keyof T & string];
+    /**
+     * A reference to a token whose value is of type `V`, in a library whose
+     * token values are `T`. It's resolved to the token's value when the token
+     * that has it is read. Made by {@link ref} and {@link refs}.
+     *
+     * @remarks
+     * A ref is data: the path of its token. `T`, the
+     * {@link (Library:namespace).TokenValues} of the library, is only in its
+     * type, so that a ref can only be given to a library that has its token.
+     *
+     * @public
+     */
+    export interface Ref<V, T> {
+        readonly [REF]: readonly string[];
+        readonly [RESOLVES]?: (library: T) => V;
+    }
+    /**
+     * A value of type `V` computed by a {@link (Library:namespace).Recipe}
+     * from its arguments, which may refer to the tokens of a library whose
+     * {@link (Library:namespace).TokenValues} are `T`. It's computed when the
+     * token that has it is read.
+     *
+     * @remarks
+     * A computed value is data: the recipe and its arguments.
+     *
+     * @public
+     */
+    export interface Computed<V, T> {
+        readonly [COMPUTED]: {
+            readonly recipe: Recipe<any, unknown>;
+            readonly args: readonly unknown[];
+        };
+        readonly [COMPUTES]?: (library: T) => V;
+    }
+    /**
+     * A value of type `V` in a configuration: the value, a
+     * {@link (Library:namespace).Ref}, a {@link (Library:namespace).Computed}
+     * value, or, when `V` is an object or an array, `V` with any of its
+     * properties and elements, at any depth, given as one of those.
+     *
+     * @remarks
+     * Its objects and arrays may be readonly, as a token's value is, so a
+     * token's value can be given where a config takes a value, as `set()`
+     * takes it. A computed value may be readonly, as a recipe's function that
+     * takes readonly arguments returns: the library copies and freezes a
+     * recipe's result.
+     *
      * @public
      */
-    type TokenLibrary<T extends {}, R extends {} = T> = {
-        [K in keyof Readonly<T>]: T[K] extends DesignToken.Any ? Token<T[K], R> : K extends "type" ? DesignToken.Type : T[K] extends {} ? TokenLibrary<T[K], R> : never;
+    export type DeepValue<V, T> = V | Ref<V, T> | Computed<DesignToken.DeepReadonly<V>, T> | (V extends object ? {
+        readonly [K in keyof V]: DeepValue<V[K], T>;
+    } : never);
+    /**
+     * The arguments of a {@link (Library:namespace).Recipe} whose function has
+     * the parameters `A`. Each may be a ref, a computed value, or a value with
+     * them in it.
+     *
+     * @public
+     */
+    export type RecipeArguments<A extends readonly unknown[], T> = {
+        [K in keyof A]: DeepValue<A[K], T>;
     };
     /**
-     * A token value that serves as an alias to another token value
+     * A function, made by {@link recipes}, that takes the arguments of a
+     * function with parameters `A` and result `V`, any of which may refer to
+     * tokens, and returns the {@link (Library:namespace).Computed} result.
+     * `T` is the token values of the library its arguments refer to.
+     *
+     * @remarks
+     * A recipe has its name and its function, which a library that extends
+     * another can override with {@link override}. The function gets each
+     * argument as a token gets its value: a ref's value, and a copy of plain
+     * data, which are frozen, and anything else as it is. So its parameters
+     * are typed readonly, as in `DesignToken.Values.Readonly.Color`.
      *
      * @public
      */
-    type Alias<T extends DesignToken.Any, R extends Context<any>> = (context: R) => T | DesignToken.ValueByToken<T>;
+    export type Recipe<A extends readonly unknown[], V> = (<T extends {} = {}>(...args: RecipeArguments<A, T>) => Computed<V, T>) & {
+        readonly [RECIPE]: {
+            readonly name: string;
+            readonly fn: (...args: A) => V;
+        };
+    };
     /**
-     * An {@link (Library:namespace).Alias} that supports complex token value types
-     * such as {@link DesignToken.Border}
+     * The {@link (Library:namespace).Recipe | recipes} of the functions of `F`,
+     * by the same keys. Made by {@link recipes}.
      *
      * @public
      */
-    type DeepAlias<V extends DesignToken.Values.Any, T extends Context<any>> = {
-        [K in keyof V]: V[K] extends DesignToken.Values.Any ? V[K] | Alias<DesignToken.TokenByValue<V[K]>, T> | DeepAlias<V[K], T> : never;
+    export type Recipes<F extends Record<string, (...args: any[]) => unknown>> = {
+        readonly [K in keyof F]: Recipe<Parameters<F[K]>, ReturnType<F[K]>>;
     };
     /**
-     * Context object provided to {@link (Library:namespace).Alias} values at runtime
+     * A function that replaces a recipe's in a library made by `extend()`.
+     * Made by {@link override}.
+     *
+     * @public
+     */
+    export interface RecipeOverride {
+        readonly recipe: Recipe<any, unknown>;
+        readonly fn: (...args: any[]) => unknown;
+    }
+    /**
+     * Options of `extend()`.
+     *
+     * @public
+     */
+    export interface ExtendOptions {
+        /**
+         * Recipes whose function is replaced in the new library, for every
+         * token that computes its value with them, including the tokens it
+         * doesn't restate.
+         */
+        readonly recipes?: readonly RecipeOverride[];
+    }
+    /**
+     * A {@link (Library:namespace).Ref} to each token of a library of shape
+     * `R`, at the path of the token in `T`, the shape of a group of it. Made by
+     * {@link refs}.
      *
      * @public
      */
-    type Context<T extends {}, R extends {} = T> = {
-        [K in keyof Readonly<T>]: T[K] extends DesignToken.Any ? Readonly<T[K]> : K extends "type" ? DesignToken.Type : T[K] extends {} ? Context<T[K], R> : never;
+    export type Refs<T extends {}, R extends {} = T> = {
+        readonly [K in keyof T as K extends keyof DesignToken.Group ? never : K]-?: T[K] extends DesignToken.Shape ? Ref<DesignToken.ValueByToken<T[K]>, TokenValues<R>> : T[K] extends {} ? Refs<T[K], R> : never;
     };
     /**
      * A token in a {@link (Library:namespace).TokenLibrary}
      *
+     * @remarks
+     * `G` is the type inherited from ancestor groups, used when
+     * `T` does not declare a `$type`.
+     *
      * @public
      */
-    type Token<T extends DesignToken.Any, C extends {}> = {
-        set(value: DesignToken.ValueByToken<T> | Alias<T, C>): void;
+    export type Token<T extends DesignToken.Shape, C extends {}, G extends string = never> = {
+        set(value: ConfigTokenValue<T, C> | DesignToken.ReadonlyValueByToken<T>): void;
+        /**
+         * A JSON representation of the token's name, type, resolved value,
+         * description, extensions and deprecation.
+         */
         toString(): string;
-        readonly type: DesignToken.TypeByToken<T>;
-        readonly extensions: Record<string, any>;
-        readonly value: DesignToken.ValueByToken<T>;
-        readonly description: string;
+        readonly $type: DesignToken.TypeByToken<T, G>;
+        readonly $extensions: Record<string, any>;
+        readonly $value: DesignToken.ReadonlyValueByToken<T>;
+        readonly $description: string;
+        /**
+         * `false`, `true`, or the explanation the token was deprecated with.
+         */
+        readonly $deprecated: boolean | string;
         readonly name: string;
     };
+    type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : never;
+    /**
+     * The type a group passes on to its descendant tokens, following
+     * {@link https://www.designtokens.org/tr/2025.10/format/#type-1 | DTCG group type inheritance}.
+     *
+     * @remarks
+     * A group passes on its own `$type` only when the group's shape declares a
+     * required, single, literal `$type`. A group with an optional or non-literal
+     * `$type` may set any type at runtime, so it passes on nothing. A group
+     * without a `$type` passes on its ancestor's type, `G`.
+     *
+     * @public
+     */
+    export type GroupType<T, G extends string = never> = "$type" extends keyof T ? {} extends Pick<T, "$type"> ? never : T["$type"] extends string ? string extends T["$type"] ? never : true extends IsUnion<T["$type"]> ? never : T["$type"] : never : G;
+    /**
+     * The value of a token in a configuration object, in a library of shape
+     * `R`: a {@link (Library:namespace).DeepValue} of the token's value type.
+     *
+     * @public
+     */
+    export type ConfigTokenValue<T extends DesignToken.Shape, R extends {}> = DeepValue<DesignToken.ValueByToken<T>, TokenValues<R>>;
+    /**
+     * A token in a configuration object.
+     *
+     * @remarks
+     * The token's `$type` may only be omitted when it matches the type
+     * inherited from ancestor groups, `G`.
+     *
+     * @public
+     */
+    export type ConfigValue<T extends DesignToken.Shape, R extends {}, G extends string = never> = T | (Omit<T, "$type" | "$value"> & ([G] extends [never] ? {
+        $type: DesignToken.TypeByToken<T>;
+    } : [DesignToken.TypeByToken<T, G>] extends [G] ? {
+        $type?: DesignToken.TypeByToken<T, G>;
+    } : {
+        $type: DesignToken.TypeByToken<T>;
+    }) & {
+        $value: ConfigTokenValue<T, R>;
+    });
     /**
      * A configuration object provided to {@link Library.create}
      *
+     * @remarks
+     * `G` is the type inherited from ancestor groups. `S` is the shape of a
+     * source library being extended: its group types are inherited, and its
+     * tokens may be overridden without restating their type.
+     *
      * @public
      */
-    type Config<T extends {}, R extends {} = T> = {
-        [K in keyof T]: T[K] extends DesignToken.Any ? ConfigValue<T[K], R> : T[K] extends {} ? Config<T[K], R> : never;
+    export type Config<T extends {}, R extends {} = T, G extends string = never, S = {}> = ConfigGroup<T, R, GroupType<T, GroupType<S, G>>, S>;
+    type ConfigGroup<T extends {}, R extends {}, G extends string, S> = {
+        [K in keyof T]: K extends keyof S ? S[K] extends DesignToken.Shape ? unknown : ConfigEntry<T, R, G, S, K> : ConfigEntry<T, R, G, S, K>;
     };
+    type ConfigEntry<T extends {}, R extends {}, G extends string, S, K extends keyof T> = T[K] extends DesignToken.Shape ? ConfigValue<T[K], R, G> : K extends keyof DesignToken.Group ? T[K] : T[K] extends {} ? Config<T[K], R, G, K extends keyof S ? S[K] : {}> : T[K] extends null | undefined ? T[K] : never;
     /**
+     * Checks the `$value` of each token in a config of shape `T` against
+     * its `$type`. It's needed when `T` is inferred from the config, because
+     * the inferred `$value` is the config's own value, so
+     * {@link (Library:namespace).Config} alone can't reject it.
+     *
+     * @remarks
+     * Only the values of tokens that declare a {@link DesignToken.Type} are
+     * checked. A token can't have a child (a key without a `$` prefix).
+     *
+     * Tokens are found by their keys rather than by `T[K] extends Shape`,
+     * which TypeScript doesn't resolve for an inferred `T` with extra keys.
+     * An `any` config, such as `Library.create<any>()`, isn't checked.
+     *
      * @public
      */
-    type ConfigValue<T extends DesignToken.Any, R extends {}> = T | (Omit<T, "value"> & {
-        value: Library.Alias<T, Context<R>> | Library.DeepAlias<DesignToken.ValueByToken<T>, Context<R>>;
-    });
+    export type ConfigValueCheck<T, R extends {}> = 0 extends 1 & T ? unknown : {
+        [K in keyof T]: 0 extends 1 & T[K] ? unknown : "$value" extends keyof T[K] ? ("$type" extends keyof T[K] ? TokenValueCheck<T[K][Extract<"$type", keyof T[K]>], R> : unknown) & {
+            [P in Exclude<keyof T[K], `$${string}`>]?: never;
+        } : T[K] extends object ? ConfigValueCheck<T[K], R> : unknown;
+    };
+    type TokenValueCheck<Type, R extends {}> = [Type] extends [
+        keyof DesignToken.ValueByType
+    ] ? {
+        $value: ConfigTokenValue<{
+            $type: Type;
+            $value: DesignToken.ValueByType[Type];
+        }, R>;
+    } : unknown;
+    /**
+     * Gives each `$type` in a config literal a contextual type, so that
+     * TypeScript keeps an inferred `$type` literal, such as
+     * `DesignToken.Type.Color`, instead of widening it to `DesignToken.Type`.
+     * {@link (Library:namespace).ConfigValueCheck} needs the literal.
+     *
+     * @remarks
+     * Configs are typed `ConfigTypeHint | {}`, so a config without an index
+     * signature, such as a typed variable, is still accepted.
+     *
+     * @public
+     */
+    export type ConfigTypeHint = {
+        readonly [key: string]: ConfigTypeHint | DesignToken.Type | (string & {}) | number | boolean | object | null | undefined;
+    };
+    /**
+     * A configuration object provided to {@link (Library:namespace).Library.extend}.
+     * All tokens and groups of the source library are optional, and token
+     * values may be static values, refs or computed values. Token types are inherited
+     * from the source library.
+     *
+     * @public
+     */
+    export type ExtendConfig<T extends {}, R extends {} = T> = {
+        [K in keyof T]?: T[K] extends DesignToken.Shape ? Omit<T[K], "$type" | "$value"> & {
+            $type?: DesignToken.TypeByToken<T[K]>;
+            $value: ConfigTokenValue<T[K], R>;
+        } : K extends keyof DesignToken.Group ? T[K] : T[K] extends {} ? ExtendConfig<T[K], R> : never;
+    };
     /**
      * @public
      */
-    const create: <T extends {} = any>(config: Library.Config<T, T>) => Library.Library<T>;
+    export const create: <T extends NoRoot<T> = any>(config: Library.Config<T, T> & NoInfer<ConfigValueCheck<T, T>> & (ConfigTypeHint | {})) => Library.Library<T>;
+    export {};
+}
+/**
+ * Thrown when reading a token whose value refers back to itself through
+ * one or more refs or computed values.
+ *
+ * @public
+ */
+export declare class CircularReferenceError extends Error {
+    readonly name = "CircularReferenceError";
+    /**
+     * The names of the tokens in the cycle, starting and ending with the
+     * same token.
+     */
+    readonly chain: string[];
+    constructor(chain: string[]);
 }
+export {};