@vicin/sigil 3.3.0 → 4.0.0

package/dist/index.d.cts

@@ -0,0 +1,374 @@
+/** -----------------------------------------
+ *  Public
+ * ----------------------------------------- */
+/**
+ * Symbol used for nominal typing
+ */
+declare const sigil: unique symbol;
+/** Update '[sigil]' field for nominal typing */
+type ExtendSigil<L extends string, P extends Sigil> = 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;
+/**
+ * Helper type to get prototype of class
+ *
+ * @template T - Class constructor.
+ */
+type GetPrototype<T> = T extends {
+    prototype: infer P;
+} ? P : never;
+/** -----------------------------------------
+ *  Internal
+ * ----------------------------------------- */
+/**
+ * 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;
+
+/**
+ * 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[]): {
+        isInstance<T>(this: T, other: any): other is T;
+        isExactInstance<T>(this: T, other: any): other is T;
+        get SigilLabel(): string;
+        get SigilLabelLineage(): readonly string[];
+        get hasOwnSigil(): boolean;
+        readonly [sigil]: {
+            Sigil: true;
+        };
+    };
+    get SigilLabel(): string;
+    get SigilLabelLineage(): readonly string[];
+    get hasOwnSigil(): boolean;
+    isInstance<T>(this: T, other: any): other is GetPrototype<T>;
+    isExactInstance<T>(this: T, other: any): other is GetPrototype<T>;
+};
+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.isInstance(someError)`).
+ */
+declare const SigilError: {
+    new (...args: any[]): {
+        [sigil]: {
+            Sigil: true;
+            SigilError: true;
+        };
+        isInstance<T>(this: T, other: any): other is T;
+        isExactInstance<T>(this: T, other: any): other is T;
+        get SigilLabel(): string;
+        get SigilLabelLineage(): readonly string[];
+        get hasOwnSigil(): boolean;
+    };
+    get SigilLabel(): string;
+    get SigilLabelLineage(): readonly string[];
+    get hasOwnSigil(): boolean;
+    isInstance<T>(this: T, other: any): other is GetPrototype<T>;
+    isExactInstance<T>(this: T, other: any): other is GetPrototype<T>;
+};
+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;
+}
+/** -----------------------------------------
+ *  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: ({ labelValidation }?: 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;
+
+/**
+ * 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 AttachSigil(label: string, opts?: SigilOptions): (target: Function, ctx: any) => void;
+/**
+ * Function that attaches runtime sigil metadata to Sigil class.
+ * Alternative to '@AttachSigil' if you prefer normal functions.
+ *
+ * @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 attachSigil<S extends Function>(Class: S, label: string, opts?: SigilOptions): S;
+
+/**
+ * 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 typeof Sigil;
+/**
+ * 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 Sigil;
+
+/**
+ * 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<L extends string>(Base: Constructor, label: L, opts?: SigilOptions): {
+    new (...args: any[]): {
+        [sigil]: {
+            Sigil: true;
+        } & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
+        /**
+         * 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.
+         */
+        isInstance<T_1>(this: T_1, other: any): other is T_1;
+        /**
+         * 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.
+         */
+        isExactInstance<T_1>(this: T_1, other: any): other is T_1;
+        /**
+         * 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').
+         */
+        get SigilLabel(): string;
+        /**
+         * Copy of the sigil label lineage for this instance's constructor.
+         *
+         * Useful for debugging and logging.
+         *
+         * @returns An array of sigil labels representing parent → child labels.
+         */
+        get SigilLabelLineage(): readonly string[];
+        /** Check if sigil label has been attached to this class */
+        get hasOwnSigil(): boolean;
+    };
+    /**
+     * Class-level identity label constant for this sigil constructor.
+     */
+    get SigilLabel(): string;
+    /**
+     * Copy of the sigil label lineage for this instance's constructor.
+     *
+     * Useful for debugging and logging.
+     *
+     * @returns An array of sigil labels representing parent → child labels.
+     */
+    get SigilLabelLineage(): readonly string[];
+    /** Check if sigil label has been attached to this class */
+    get hasOwnSigil(): boolean;
+    /**
+     * 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.
+     */
+    isInstance<T>(this: T, other: any): 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.
+     */
+    isExactInstance<T>(this: T, other: any): other is GetPrototype<T>;
+};
+/**
+ * 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<L extends string>(Base: ConstructorAbstract, label: L, opts?: SigilOptions): (abstract new (...args: any[]) => {
+    [sigil]: {
+        Sigil: true;
+    } & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
+    /**
+     * 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.
+     */
+    isInstance<T_1>(this: T_1, other: any): other is T_1;
+    /**
+     * 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.
+     */
+    isExactInstance<T_1>(this: T_1, other: any): other is T_1;
+    /**
+     * 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').
+     */
+    get SigilLabel(): string;
+    /**
+     * Copy of the sigil label lineage for this instance's constructor.
+     *
+     * Useful for debugging and logging.
+     *
+     * @returns An array of sigil labels representing parent → child labels.
+     */
+    get SigilLabelLineage(): readonly string[];
+    /** Check if sigil label has been attached to this class */
+    get hasOwnSigil(): boolean;
+}) & {
+    /**
+     * Class-level identity label constant for this sigil constructor.
+     */
+    get SigilLabel(): string;
+    /**
+     * Copy of the sigil label lineage for this instance's constructor.
+     *
+     * Useful for debugging and logging.
+     *
+     * @returns An array of sigil labels representing parent → child labels.
+     */
+    get SigilLabelLineage(): readonly string[];
+    /** Check if sigil label has been attached to this class */
+    get hasOwnSigil(): boolean;
+    /**
+     * 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.
+     */
+    isInstance<T>(this: T, other: any): 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.
+     */
+    isExactInstance<T>(this: T, other: any): other is GetPrototype<T>;
+};
+
+declare function hasOwnSigil(ctor: Function): boolean;
+
+export { AttachSigil, type ExtendSigil, type GetPrototype, RECOMMENDED_LABEL_REGEX, Sigil, SigilError, type SigilOf, type SigilOptions, Sigilify, SigilifyAbstract, attachSigil, hasOwnSigil, isSigilCtor, isSigilInstance, sigil, updateSigilOptions };