@vicin/sigil 3.3.0 → 4.0.0

package/dist/index.d.ts

@@ -1,117 +1,12 @@
 /** -----------------------------------------
- *  Nominal identity symbol
+ *  Public
  * ----------------------------------------- */
 /**
  * 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>, {}> & {
+type ExtendSigil<L extends string, P extends Sigil> = Prettify<IfNever<SigilOf<P>, {}> & {
     [K in L]: true;
 }>;
 /**
@@ -123,8 +18,16 @@ type ExtendSigil<L extends string, P extends ISigilInstance> = Prettify<IfNever<
 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;
 /** -----------------------------------------
- *  Generic types
+ *  Internal
  * ----------------------------------------- */
 /**
  * Generic type for class constructors used by the Sigil utilities.
@@ -152,14 +55,6 @@ type Prettify<T> = {
 } & {};
 /** 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.
@@ -169,24 +64,20 @@ type GetPrototype<T> = T extends {
  */
 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>>;
+        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(): "Sigil";
-    get SigilEffectiveLabel(): "Sigil";
+    get SigilLabel(): string;
     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 (): {};
+    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>;
 /**
@@ -194,28 +85,26 @@ type Sigil = InstanceType<typeof Sigil>;
  * 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)`).
+ * runtime checks (e.g. `SigilError.isInstance(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]: {
             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(): "SigilError";
-    get SigilEffectiveLabel(): "SigilError";
+    get SigilLabel(): string;
     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;
+    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>;
 
 /** -----------------------------------------
@@ -237,18 +126,6 @@ interface SigilOptions {
      * 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
@@ -259,7 +136,7 @@ interface SigilOptions {
  *
  * @param opts - Partial options to merge into the global `OPTIONS` object.
  */
-declare const updateSigilOptions: (opts: SigilOptions) => void;
+declare const updateSigilOptions: ({ labelValidation }?: SigilOptions) => void;
 /** -----------------------------------------
  *  Label validation
  * ----------------------------------------- */
@@ -271,8 +148,6 @@ declare const updateSigilOptions: (opts: SigilOptions) => void;
  * 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.
@@ -281,11 +156,10 @@ declare const DEFAULT_LABEL_REGEX: RegExp;
  * @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;
-
+declare function AttachSigil(label: string, opts?: SigilOptions): (target: Function, ctx: any) => void;
 /**
- * HOF (class inhancer) that attaches runtime sigil metadata to Sigil class.
- * Alternative to '@WithSigil' if you prefer HOFs.
+ * 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.
@@ -293,18 +167,15 @@ declare function WithSigil(label: string, opts?: SigilOptions): (value: Function
  * @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;
+declare function attachSigil<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;
+declare function isSigilCtor(ctor: unknown): ctor is typeof Sigil;
 /**
  * Runtime predicate that checks whether the provided object is an instance
  * of a sigil class.
@@ -312,12 +183,7 @@ declare function isSigilCtor(ctor: unknown): ctor is ISigil;
  * @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[];
+declare function isSigilInstance(inst: unknown): inst is Sigil;
 
 /**
  * Mixin factory that augments an existing class with Sigil runtime metadata and helpers.
@@ -328,8 +194,11 @@ declare function getSigilLabels(): string[];
  * @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): {
+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.
@@ -342,7 +211,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
          * @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;
+        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.
@@ -352,61 +221,38 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
          * @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;
+        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').
          */
-        getSigilLabel(): string;
+        get SigilLabel(): string;
         /**
-         * Returns the human-readable sigil label of this instance's constructor.
+         * Copy of the sigil label lineage for 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.
+         * Useful for debugging and logging.
          *
-         * @returns readonly array of labels representing the type lineage.
-         */
-        getSigilLabelSet(): Readonly<Set<string>>;
-        /**
-         * Compile-time nominal brand that encodes the class sigil labels object.
+         * @returns An array of sigil labels representing parent → child labels.
          */
-        readonly [sigil]: {
-            Sigil: true;
-        } & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
+        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(): L;
-    /**
-     * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
-     */
-    get SigilEffectiveLabel(): L;
+    get SigilLabel(): string;
     /**
-     * Linearized sigil type label chain for the current constructor.
+     * Copy of the sigil label lineage for this instance's constructor.
      *
-     * Useful for debugging and performing strict lineage comparisons.
+     * Useful for debugging and logging.
      *
-     * @returns An array of labels representing parent → child type labels.
+     * @returns An array of sigil labels representing parent → child 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 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.
@@ -419,7 +265,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
      * @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>;
+    isInstance<T>(this: T, other: any): other is GetPrototype<T>;
     /**
      * Check whether `other` is exactly the same instance represented by the
      * calling constructor.
@@ -429,8 +275,8 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
      * @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;
+    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.
  *
@@ -440,7 +286,10 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
  * @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[]) => {
+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.
@@ -453,7 +302,7 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @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;
+    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.
@@ -463,61 +312,38 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @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;
+    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').
      */
-    getSigilLabel(): string;
+    get SigilLabel(): string;
     /**
-     * Returns the human-readable sigil label of this instance's constructor.
+     * Copy of the sigil label lineage for 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.
+     * Useful for debugging and logging.
      *
-     * @returns readonly array of labels representing the type lineage.
+     * @returns An array of sigil labels representing parent → child labels.
      */
-    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;
+    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(): L;
+    get SigilLabel(): string;
     /**
-     * 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.
+     * Copy of the sigil label lineage for this instance's constructor.
      *
-     * Useful for debugging and performing strict lineage comparisons.
+     * Useful for debugging and logging.
      *
-     * @returns An array of labels representing parent → child type labels.
+     * @returns An array of sigil labels representing parent → child 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 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.
@@ -530,7 +356,7 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @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>;
+    isInstance<T>(this: T, other: any): other is GetPrototype<T>;
     /**
      * Check whether `other` is exactly the same instance represented by the
      * calling constructor.
@@ -540,7 +366,9 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @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;
+    isExactInstance<T>(this: T, other: any): other is GetPrototype<T>;
+};
+
+declare function hasOwnSigil(ctor: Function): boolean;
 
-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 };
+export { AttachSigil, type ExtendSigil, type GetPrototype, RECOMMENDED_LABEL_REGEX, Sigil, SigilError, type SigilOf, type SigilOptions, Sigilify, SigilifyAbstract, attachSigil, hasOwnSigil, isSigilCtor, isSigilInstance, sigil, updateSigilOptions };