@vicin/sigil 3.3.0 → 4.0.0

package/dist/index.d.mts

@@ -1,546 +0,0 @@
-/** -----------------------------------------
- *  Nominal identity symbol
- * ----------------------------------------- */
-/**
- * Symbol used for nominal typing
- */
-declare const sigil: unique symbol;
-/** -----------------------------------------
- *  Class and instance
- * ----------------------------------------- */
-/**
- * Static-side interface describing methods and properties added to a class
- * constructor when it is sigilified.
- *
- * The properties and methods described here mirror the getters and static
- * predicates implemented by the `Sigilify` mixin.
- *
- * @template L - Narrow string literal type representing the label.
- * @template P - Optinal parent to extend its '[sigil]'.
- */
-interface ISigilStatic<L extends string = string> {
-    /** Class-level label constant (identity). */
-    readonly SigilLabel: L;
-    /** Class-level label constant (human readable). */
-    readonly SigilEffectiveLabel: L;
-    /**
-     * Copy of the linearized sigil type label chain for the current constructor.
-     * Useful for debugging.
-     */
-    readonly SigilLabelLineage: readonly string[];
-    /**
-     * Copy of the sigil type label set for the current constructor.
-     * Useful for debugging.
-     */
-    readonly SigilLabelSet: Readonly<Set<string>>;
-    /**
-     * Check whether `other` is (or inherits from) the instance represented by the
-     * calling constructor.
-     *
-     * This replaces `instanceof` so that checks remain valid across bundles/realms
-     * and when subclassing.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isOfType<T extends ISigilStatic>(this: T, other: unknown): other is GetPrototype<T>;
-    /**
-     * Check whether `other` is exactly the same instance represented by the
-     * calling constructor.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isExactType<T extends ISigilStatic>(this: T, other: unknown): other is GetPrototype<T>;
-}
-/**
- * Instance-side interface describing properties present on sigil instances.
- * The methods mirror the instance helpers injected by the mixin.
- *
- * @template L - Narrow string literal type for the label returned by `getSigilLabel`.
- * @template P - Optinal parent to extend its '[sigil]'.
- */
-interface ISigilInstance<L extends string = string, P extends Function = never> {
-    /** Compile-time nominal brand that encodes the class label `L` plus parent's sigil labels `SigilOf<P>`. */
-    readonly [sigil]: Prettify<{
-        Sigil: true;
-    } & IfNever<SigilOf<P>, {}> & {
-        [k in L]: true;
-    }>;
-    /** Returns identity sigil label of the class constructor. */
-    getSigilLabel(): string;
-    /** Returns human-readable sigil label of the class constructor. */
-    getSigilEffectiveLabel(): string;
-    /** Returns copy of sigil type label lineage of the class constructor. */
-    getSigilLabelLineage(): readonly string[];
-    /** Returns copy of sigil type label set of the class constructor. */
-    getSigilLabelSet(): Readonly<Set<string>>;
-    /**
-     * Check whether `other` is (or inherits from) the instance represented by the
-     * calling constructor.
-     *
-     * This replaces `instanceof` so that checks remain valid across bundles/realms
-     * and when subclassing.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isOfType<T extends ISigilInstance>(this: T, other: unknown): other is T;
-    /**
-     * Check whether `other` is exactly the same instance represented by the
-     * calling constructor.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isExactType<T extends ISigilInstance>(this: T, other: unknown): other is T;
-}
-/**
- * Combined constructor + static interface for a sigil class.
- *
- * @template L - Narrow string literal type for the label.
- * @template P - Optinal parent to extend its '[sigil]'.
- */
-type ISigil<L extends string = string, P extends Function = never> = ConstructorAbstract<ISigilInstance<L, P>> & ISigilStatic<L>;
-/** Update '[sigil]' field for nominal typing */
-type ExtendSigil<L extends string, P extends ISigilInstance> = Prettify<IfNever<SigilOf<P>, {}> & {
-    [K in L]: true;
-}>;
-/**
- * Extract the compile-time label map from a sigil instance `S`.
- *
- * @typeParam S - A sigil instance type.
- * @returns The sigil label record (e.g. `{ User: true, Admin: true }`) or never if not Sigil class instance.
- */
-type SigilOf<S> = S extends {
-    readonly [sigil]: infer Sigil;
-} ? Sigil : never;
-/** -----------------------------------------
- *  Generic types
- * ----------------------------------------- */
-/**
- * Generic type for class constructors used by the Sigil utilities.
- *
- * - `T` is the instance type produced by the constructor.
- * - `P` is the tuple of parameter types accepted by the constructor.
- *
- * @template T - Instance type produced by the constructor (defaults to `object`).
- * @template P - Parameter tuple type for the constructor.
- */
-type Constructor<T = object, P extends any[] = any[]> = new (...args: P) => T;
-/**
- * Generic type for class constructors used by the Sigil utilities. for 'abstract classes'.
- *
- * - `T` is the instance type produced by the constructor.
- * - `P` is the tuple of parameter types accepted by the constructor.
- *
- * @template T - Instance type produced by the constructor (defaults to `object`).
- * @template P - Parameter tuple type for the constructor.
- */
-type ConstructorAbstract<T = object, P extends any[] = any[]> = abstract new (...args: P) => T;
-/** Helper type to prettify value */
-type Prettify<T> = {
-    [K in keyof T]: T[K];
-} & {};
-/** Helper type to replace 'never' with another type */
-type IfNever<T, R = {}> = [T] extends [never] ? R : T;
-/**
- * Helper type to get prototype of class
- *
- * @template T - Class constructor.
- */
-type GetPrototype<T> = T extends {
-    prototype: infer P;
-} ? P : never;
-
-/**
- * A minimal root Sigil class used by the library as a base identity.
- *
- * This is produced by `Sigilify` and can serve as a basic sentinel/base
- * class for other sigil classes or for debugging/inspection.
- */
-declare const Sigil: {
-    new (...args: any[]): {
-        isOfType<T extends ISigilInstance>(this: T, other: unknown): other is T;
-        isExactType<T extends ISigilInstance>(this: T, other: unknown): other is T;
-        getSigilLabel(): string;
-        getSigilEffectiveLabel(): string;
-        getSigilLabelLineage(): readonly string[];
-        getSigilLabelSet(): Readonly<Set<string>>;
-        readonly [sigil]: {
-            Sigil: true;
-        };
-    };
-    get SigilLabel(): "Sigil";
-    get SigilEffectiveLabel(): "Sigil";
-    get SigilLabelLineage(): readonly string[];
-    get SigilLabelSet(): Readonly<Set<string>>;
-    isOfType<T extends ISigilStatic>(this: T, other: unknown): other is GetPrototype<T>;
-    isExactType<T extends ISigilStatic>(this: T, other: unknown): other is GetPrototype<T>;
-} & {
-    new (): {};
-};
-type Sigil = InstanceType<typeof Sigil>;
-/**
- * A sigil variant of the built-in `Error` constructor used by the library
- * to represent Sigil-specific errors.
- *
- * Use `SigilError` when you want an Error type that is identifiable via sigil
- * runtime checks (e.g. `SigilError.isOfType(someError)`).
- */
-declare const SigilError: {
-    new (...args: any[]): {
-        isOfType<T extends ISigilInstance>(this: T, other: unknown): other is T;
-        isExactType<T extends ISigilInstance>(this: T, other: unknown): other is T;
-        getSigilLabel(): string;
-        getSigilEffectiveLabel(): string;
-        getSigilLabelLineage(): readonly string[];
-        getSigilLabelSet(): Readonly<Set<string>>;
-        readonly [sigil]: {
-            Sigil: true;
-            SigilError: true;
-        };
-    };
-    get SigilLabel(): "SigilError";
-    get SigilEffectiveLabel(): "SigilError";
-    get SigilLabelLineage(): readonly string[];
-    get SigilLabelSet(): Readonly<Set<string>>;
-    isOfType<T extends ISigilStatic>(this: T, other: unknown): other is GetPrototype<T>;
-    isExactType<T extends ISigilStatic>(this: T, other: unknown): other is GetPrototype<T>;
-} & ErrorConstructor;
-type SigilError = InstanceType<typeof SigilError>;
-
-/** -----------------------------------------
- *  Types
- * ----------------------------------------- */
-/**
- * Configuration options for the Sigil library.
- *
- * These options control runtime validation, inheritance checks, label autofill behavior.
- */
-interface SigilOptions {
-    /**
-     * Validation rule applied to sigil labels before registration.
-     *
-     * - A function receives the label and must return `true` if valid.
-     * - A `RegExp` must match the label.
-     * - `null` disables validation entirely.
-     *
-     * Defaults to `null`.
-     */
-    labelValidation?: ((label: string) => boolean) | RegExp | null;
-    /**
-     * When enabled, non-decorated subclasses that would otherwise inherit an ancestor's label
-     * will be assigned an autogenerated random label (so that explicit labels stay unique).
-     */
-    autofillLabels?: boolean;
-    /**
-     * Option for Hot module reload set-ups, reload of files can result in class redefinition which will throw
-     * duplicate label error, setting this to 'true' will disabel this error.
-     * However as it disables unique label check bugs can appear if the same label is passed to two different
-     * classes so set this to 'true' only when needed and ensure uniqueness of passed labels.
-     */
-    skipLabelUniquenessCheck?: boolean;
-}
-/** -----------------------------------------
- *  Update options
- * ----------------------------------------- */
-/**
- * Update runtime options for the Sigil library.
- * Call this early during application startup if you want non-default behavior.
- *
- * @param opts - Partial options to merge into the global `OPTIONS` object.
- */
-declare const updateSigilOptions: (opts: SigilOptions) => void;
-/** -----------------------------------------
- *  Label validation
- * ----------------------------------------- */
-/**
- * Label validation regex. Labels must follow the pattern
- * `@scope/package.ClassName` where `ClassName` begins with an uppercase
- * letter. This avoids collisions across packages and helps debugging.
- *
- * It's advised to use this regex in 'SigilOptions.labelValidation'.
- */
-declare const RECOMMENDED_LABEL_REGEX: RegExp;
-/** @deprecated - Use 'RECOMMENDED_LABEL_REGEX' instead, will be removed in v4 */
-declare const DEFAULT_LABEL_REGEX: RegExp;
-
-/**
- * Class decorator factory that attaches sigil statics to a class constructor.
- *
- * @param label - Sigil label string to assign to the decorated class (e.g. `@scope/pkg.ClassName`).
- * @param opts - Options object to override any global options if needed.
- * @returns A class decorator compatible with the ECMAScript decorator context.
- */
-declare function WithSigil(label: string, opts?: SigilOptions): (value: Function, context: any) => void;
-
-/**
- * HOF (class inhancer) that attaches runtime sigil metadata to Sigil class.
- * Alternative to '@WithSigil' if you prefer HOFs.
- *
- * @typeParam S - Constructor type (should be an instance of sigil class).
- * @param Class - The constructor (class) to enhance.
- * @param label - Sigil label string to assign to the decorated class (e.g. `@scope/pkg.ClassName`).
- * @param opts - Options object to override any global options if needed.
- * @returns The same constructor value, with runtime metadata ensured.
- */
-declare function withSigil<S extends Function>(Class: S, label: string, opts?: SigilOptions): S;
-
-/** -----------------------------------------
- *  Inspection helpers
- * ----------------------------------------- */
-/**
- * Runtime predicate that checks whether the provided value is a sigil constructor.
- *
- * @param ctor - Constructor to test.
- * @returns `true` if `value` is a sigil constructor, otherwise `false`.
- */
-declare function isSigilCtor(ctor: unknown): ctor is ISigil;
-/**
- * Runtime predicate that checks whether the provided object is an instance
- * of a sigil class.
- *
- * @param inst - The instanca to test.
- * @returns `true` if `obj` is an instance produced by a sigil constructor.
- */
-declare function isSigilInstance(inst: unknown): inst is ISigilInstance;
-/**
- * Helper function to get labels registered by 'Sigil'
- * @returns Sigil labels registered
- */
-declare function getSigilLabels(): string[];
-
-/**
- * Mixin factory that augments an existing class with Sigil runtime metadata and helpers.
- *
- * @param Base - The base constructor to extend.
- * @param label - Identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
- * @param opts - Options object to override any global options if needed.
- * @returns A new constructor that extends `Base` and includes Sigil statics/instance methods.
- * @throws Error if `Base` is already sigilified.
- */
-declare function Sigilify<B extends Constructor, L extends string>(Base: B, label: L, opts?: SigilOptions): {
-    new (...args: any[]): {
-        /**
-         * Check whether `other` is (or inherits from) the instance represented by the
-         * calling constructor.
-         *
-         * This replaces `instanceof` so that checks remain valid across bundles/realms
-         * and when subclassing.
-         *
-         * @typeParam T - The specific sigil constructor (`this`).
-         * @param this - The constructor performing the type check.
-         * @param other - The object to test.
-         * @returns A type guard asserting `other` is an instance of the constructor.
-         */
-        isOfType<T extends ISigilInstance>(this: T, other: unknown): other is T;
-        /**
-         * Check whether `other` is exactly the same instance represented by the
-         * calling constructor.
-         *
-         * @typeParam T - The specific sigil constructor (`this`).
-         * @param this - The constructor performing the type check.
-         * @param other - The object to test.
-         * @returns A type guard asserting `other` is an instance of the constructor.
-         */
-        isExactType<T extends ISigilInstance>(this: T, other: unknown): other is T;
-        /**
-         * Returns the identity sigil label of this instance's constructor.
-         *
-         * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:1:pnf11bgl').
-         */
-        getSigilLabel(): string;
-        /**
-         * Returns the human-readable sigil label of this instance's constructor.
-         *
-         * @returns The last passed label string (e.g. '@scope/pkg.ClassName').
-         */
-        getSigilEffectiveLabel(): string;
-        /**
-         * Returns a copy of the sigil type label lineage for this instance's constructor.
-         *
-         * @returns readonly array of labels representing the type lineage.
-         */
-        getSigilLabelLineage(): readonly string[];
-        /**
-         * Returns a copy of the sigil type label lineage set for this instance's constructor.
-         *
-         * @returns readonly array of labels representing the type lineage.
-         */
-        getSigilLabelSet(): Readonly<Set<string>>;
-        /**
-         * Compile-time nominal brand that encodes the class sigil labels object.
-         */
-        readonly [sigil]: {
-            Sigil: true;
-        } & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
-    };
-    /**
-     * Class-level identity label constant for this sigil constructor.
-     */
-    get SigilLabel(): L;
-    /**
-     * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
-     */
-    get SigilEffectiveLabel(): L;
-    /**
-     * Linearized sigil type label chain for the current constructor.
-     *
-     * Useful for debugging and performing strict lineage comparisons.
-     *
-     * @returns An array of labels representing parent → child type labels.
-     */
-    get SigilLabelLineage(): readonly string[];
-    /**
-     * Sigil type label set for the current constructor.
-     * Useful for debugging.
-     *
-     * @returns A Readonly Set of labels that represent the type lineage.
-     */
-    get SigilLabelSet(): Readonly<Set<string>>;
-    /**
-     * Check whether `other` is (or inherits from) the instance represented by the
-     * calling constructor.
-     *
-     * This replaces `instanceof` so that checks remain valid across bundles/realms
-     * and when subclassing.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isOfType<T extends ISigilStatic>(this: T, other: unknown): other is GetPrototype<T>;
-    /**
-     * Check whether `other` is exactly the same instance represented by the
-     * calling constructor.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isExactType<T extends ISigilStatic>(this: T, other: unknown): other is GetPrototype<T>;
-} & B;
-/**
- * Mixin factory that augments an existing class with Sigil runtime metadata and helpers. Accept and return 'abstract' class.
- *
- * @param Base - The base constructor to extend.
- * @param label - Identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
- * @param opts - Options object to override any global options if needed.
- * @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
- * @throws Error if `Base` is already sigilified.
- */
-declare function SigilifyAbstract<B extends ConstructorAbstract, L extends string>(Base: B, label: L, opts?: SigilOptions): ((abstract new (...args: any[]) => {
-    /**
-     * Check whether `other` is (or inherits from) the instance represented by the
-     * calling constructor.
-     *
-     * This replaces `instanceof` so that checks remain valid across bundles/realms
-     * and when subclassing.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isOfType<T>(this: T, other: unknown): other is T;
-    /**
-     * Check whether `other` is exactly the same instance represented by the
-     * calling constructor.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isExactType<T>(this: T, other: unknown): other is T;
-    /**
-     * Returns the identity sigil label of this instance's constructor.
-     *
-     * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil-auto:ClassName:1:pnf11bgl').
-     */
-    getSigilLabel(): string;
-    /**
-     * Returns the human-readable sigil label of this instance's constructor.
-     *
-     * @returns The last passed label string (e.g. '@scope/pkg.ClassName').
-     */
-    getSigilEffectiveLabel(): string;
-    /**
-     * Returns a copy of the sigil type label lineage for this instance's constructor.
-     *
-     * @returns readonly array of labels representing the type lineage.
-     */
-    getSigilLabelLineage(): readonly string[];
-    /**
-     * Returns a copy of the sigil type label lineage set for this instance's constructor.
-     *
-     * @returns readonly array of labels representing the type lineage.
-     */
-    getSigilLabelSet(): Readonly<Set<string>>;
-    /**
-     * Compile-time nominal brand that encodes the class sigil labels object.
-     */
-    readonly [sigil]: {
-        Sigil: true;
-    } & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
-}) & {
-    /**
-     * Class-level identity label constant for this sigil constructor.
-     */
-    get SigilLabel(): L;
-    /**
-     * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
-     */
-    get SigilEffectiveLabel(): L;
-    /**
-     * Linearized sigil type label chain for the current constructor.
-     *
-     * Useful for debugging and performing strict lineage comparisons.
-     *
-     * @returns An array of labels representing parent → child type labels.
-     */
-    get SigilLabelLineage(): readonly string[];
-    /**
-     * Sigil type label set for the current constructor.
-     * Useful for debugging.
-     *
-     * @returns A Readonly Set of labels that represent the type lineage.
-     */
-    get SigilLabelSet(): Readonly<Set<string>>;
-    /**
-     * Check whether `other` is (or inherits from) the instance represented by the
-     * calling constructor.
-     *
-     * This replaces `instanceof` so that checks remain valid across bundles/realms
-     * and when subclassing.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isOfType<T>(this: T, other: unknown): other is GetPrototype<T>;
-    /**
-     * Check whether `other` is exactly the same instance represented by the
-     * calling constructor.
-     *
-     * @typeParam T - The specific sigil constructor (`this`).
-     * @param this - The constructor performing the type check.
-     * @param other - The object to test.
-     * @returns A type guard asserting `other` is an instance of the constructor.
-     */
-    isExactType<T>(this: T, other: unknown): other is GetPrototype<T>;
-}) & B;
-
-export { DEFAULT_LABEL_REGEX, type ExtendSigil, type GetPrototype, type ISigil, type ISigilInstance, type ISigilStatic, RECOMMENDED_LABEL_REGEX, Sigil, SigilError, type SigilOf, type SigilOptions, Sigilify, SigilifyAbstract, WithSigil, getSigilLabels, isSigilCtor, isSigilInstance, sigil, updateSigilOptions, withSigil };