@vicin/sigil 2.2.1 → 3.0.0

package/dist/index.d.mts

@@ -1,3 +1,10 @@
+/** -----------------------------------------
+ *  Nominal identity symbol
+ * ----------------------------------------- */
+/**
+ * Symbol used for nominal typing
+ */
+declare const sigil: unique symbol;
 /** -----------------------------------------
  *  Class and instance
  * ----------------------------------------- */
@@ -9,23 +16,13 @@
  * predicates implemented by the `Sigilify` mixin.
  *
  * @template L - Narrow string literal type representing the label.
- * @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
+ * @template P - Optinal parent to extend its '[sigil]'.
  */
-interface ISigilStatic<L extends string = string, P extends Function = never> {
-    /**
-     * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
-     *
-     * - HAVE NO RUN-TIME VALUE (undefined)
-     * - Provides a *type-only* unique marker that makes instances nominally
-     *   distinct by label and allows propagation/merging of brand keys across inheritance.
-     */
-    readonly __SIGIL_BRAND__: Prettify<{
-        [k in L]: true;
-    } & SigilBrandOf<P>>;
+interface ISigilStatic<L extends string = string> {
     /** Class-level label constant (identity). */
-    readonly SigilLabel: string;
+    readonly SigilLabel: L;
     /** Class-level label constant (human readable). */
-    readonly SigilEffectiveLabel: string;
+    readonly SigilEffectiveLabel: L;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      * Useful for debugging and strict lineage comparisons.
@@ -60,7 +57,7 @@ interface ISigilStatic<L extends string = string, P extends Function = never> {
      * @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 GetInstance<T>;
+    isOfType<T extends ISigilStatic>(this: T, other: unknown): other is T;
     /**
      * Strict lineage comparison: verifies that the calling constructor's type
      * lineage (by label) matches the `other`'s lineage element-by-element.
@@ -73,14 +70,14 @@ interface ISigilStatic<L extends string = string, P extends Function = never> {
      * @param other - The object to test.
      * @returns A type guard asserting `other` is an instance whose lineage matches exactly.
      */
-    isOfTypeStrict<T extends ISigilStatic>(this: T, other: unknown): other is GetInstance<T>;
+    isOfTypeStrict<T extends ISigilStatic>(this: T, other: unknown): other is 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_BRAND__'.
+ * @template P - Optinal parent to extend its '[sigil]'.
  */
 interface ISigilInstance<L extends string = string, P extends Function = never> {
     /**
@@ -90,9 +87,9 @@ interface ISigilInstance<L extends string = string, P extends Function = never>
      * - Provides a *type-only* unique marker that makes instances nominally
      *   distinct by label and allows propagation/merging of brand keys across inheritance.
      */
-    readonly __SIGIL_BRAND__: Prettify<{
+    readonly [sigil]: Prettify<IfNever<SigilOf<P>, {}> & {
         [k in L]: true;
-    } & SigilBrandOf<P>>;
+    }>;
     /** Returns identity sigil label of the class constructor. */
     getSigilLabel(): string;
     /** Returns human-readable sigil label of the class constructor. */
@@ -114,7 +111,7 @@ interface ISigilInstance<L extends string = string, P extends Function = never>
      * @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 GetInstance<T>;
+    isOfType<T extends ISigilInstance>(this: T, other: unknown): other is T;
     /**
      * Strict lineage comparison: verifies that the calling constructor's type
      * lineage (by label) matches the `other`'s lineage element-by-element.
@@ -127,66 +124,31 @@ interface ISigilInstance<L extends string = string, P extends Function = never>
      * @param other - The object to test.
      * @returns A type guard asserting `other` is an instance whose lineage matches exactly.
      */
-    isOfTypeStrict<T extends ISigilInstance>(this: T, other: unknown): other is GetInstance<T>;
+    isOfTypeStrict<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_BRAND__'.
+ * @template P - Optinal parent to extend its '[sigil]'.
  */
-type ISigil<L extends string = string, P extends Function = never> = ConstructorAbstract<ISigilInstance<L, P>> & ISigilStatic<L, P>;
-/** -----------------------------------------
- *  HOF pattern types
- * ----------------------------------------- */
+type ISigil<L extends string = string, P extends Function = never> = ConstructorAbstract<ISigilInstance<L, P>> & ISigilStatic<L>;
+/** Update '[sigil]' field when manual typing is used. */
+type ExtendSigil<L extends string, P extends ISigilInstance> = Prettify<IfNever<SigilOf<P>, {}> & {
+    [K in L]: true;
+}>;
 /**
- * Combine an existing sigil constructor type `S` with a **new** label `L`,
- * while inheriting/propagating compile-time brands from an optional parent sigil `P`.
+ * Extract the compile-time brand map from a sigil instance `S`.
  *
- * @template S - The original Untyped Sigil constructor type being augmented.
- * @template L - The new label literal to associate with the resulting constructor.
+ * @typeParam S - A sigil instance type.
+ * @returns The sigil brand record (e.g. `{ User: true, Admin: true }`) or never if not Sigil class instance.
  */
-type TypedSigil<S extends Function, L extends string = string> = S & AppendLabel<L> & ConstructorAbstract<AppendLabel<L>>;
-/**
- * Generic helper extract instance of the class even in protected and private constructors.
- * @remark Return same type is passed type has no 'prototype'
- */
-type GetInstance<T> = T extends {
-    prototype: infer R;
-} ? PrettifyBrand<R & {
-    __SIGIL_BRAND__: SigilBrandOf<T>;
-}> : T;
-/** Helper to append label into a class. */
-type AppendLabel<L extends string> = {
-    readonly __SIGIL_BRAND__: Prettify<{
-        [K in L]: true;
-    }>;
-};
-/** -----------------------------------------
- *  Manual pattern types
- * ----------------------------------------- */
-/** Update '__SIGIL_BRAND__' field when manual typing is used. */
-type UpdateSigilBrand<L extends string, P extends ISigilInstance> = Prettify<SigilBrandOf<P> & {
-    [K in L]: true;
-}>;
+type SigilOf<S> = S extends {
+    readonly [sigil]: infer Sigil;
+} ? Sigil : never;
 /** -----------------------------------------
  *  Generic types
  * ----------------------------------------- */
-/**
- * Extract the compile-time brand map from a sigil constructor `S`.
- *
- * @typeParam S - A sigil constructor type (e.g. `typeof SomeSigilClass`).
- * @returns The brand record carried on the constructor's instance type (e.g. `{ User: true, Admin: true }`).
- *
- * @remarks
- * - This helper is used purely at the type level to compute the set of brand keys
- *   that should be propagated to derived sigils.
- * - If `S` does not carry a `__SIGIL_BRAND__`, the resulting type is `never` and `IfNever<>`
- *   collapses it to an empty record.
- */
-type SigilBrandOf<S> = IfNever<S extends {
-    readonly __SIGIL_BRAND__: infer Brand;
-} ? Brand : never, Record<string, true>>;
 /**
  * Generic type for class constructors used by the Sigil utilities.
  *
@@ -211,10 +173,6 @@ type ConstructorAbstract<T = object, P extends any[] = any[]> = abstract new (..
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
-/** Helper type to prettify value, handles nested '__SIGIL_BRAND__' field */
-type PrettifyBrand<T> = {
-    [K in keyof T]: K extends '__SIGIL_BRAND__' ? PrettifyBrand<T[K]> : T[K];
-} & {};
 /** Helper type to replace 'never' with another type */
 type IfNever<T, R = {}> = [T] extends [never] ? R : T;
 
@@ -226,30 +184,27 @@ type IfNever<T, R = {}> = [T] extends [never] ? R : T;
  */
 declare const Sigil: {
     new (...args: any[]): {
-        readonly __SIGIL_BRAND__: {
-            Sigil: true;
-        };
-        isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
-        isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
+        isOfType<T>(this: T, other: unknown): other is T;
+        isOfTypeStrict<T>(this: T, other: unknown): other is T;
         getSigilLabel(): string;
         getSigilEffectiveLabel(): string;
         getSigilLabelLineage(): readonly string[];
         getSigilLabelSet(): Readonly<Set<string>>;
+        readonly [sigil]: {
+            Sigil: true;
+        };
     };
-    readonly __SIGIL_BRAND__: {
-        Sigil: true;
-    };
-    get SigilLabel(): string;
-    get SigilEffectiveLabel(): string;
+    get SigilLabel(): "Sigil";
+    get SigilEffectiveLabel(): "Sigil";
     get SigilLabelLineage(): readonly string[];
     get SigilLabelSet(): Readonly<Set<string>>;
     isSigilified(obj: unknown): obj is ISigil;
-    isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
-    isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
+    isOfType<T>(this: T, other: unknown): other is T;
+    isOfTypeStrict<T>(this: T, other: unknown): other is T;
 } & {
     new (): {};
 };
-type Sigil = GetInstance<typeof Sigil>;
+type Sigil = InstanceType<typeof Sigil>;
 /**
  * A sigil variant of the built-in `Error` constructor used by the library
  * to represent Sigil-specific errors.
@@ -259,30 +214,26 @@ type Sigil = GetInstance<typeof Sigil>;
  */
 declare const SigilError: {
     new (...args: any[]): {
-        readonly __SIGIL_BRAND__: {
-            Sigil: true;
-            SigilError: true;
-        };
-        isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
-        isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
+        isOfType<T>(this: T, other: unknown): other is T;
+        isOfTypeStrict<T>(this: T, other: unknown): other is T;
         getSigilLabel(): string;
         getSigilEffectiveLabel(): string;
         getSigilLabelLineage(): readonly string[];
         getSigilLabelSet(): Readonly<Set<string>>;
+        readonly [sigil]: {
+            Sigil: true;
+            SigilError: true;
+        };
     };
-    readonly __SIGIL_BRAND__: {
-        Sigil: true;
-        SigilError: true;
-    };
-    get SigilLabel(): string;
-    get SigilEffectiveLabel(): string;
+    get SigilLabel(): "SigilError";
+    get SigilEffectiveLabel(): "SigilError";
     get SigilLabelLineage(): readonly string[];
     get SigilLabelSet(): Readonly<Set<string>>;
     isSigilified(obj: unknown): obj is ISigil;
-    isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
-    isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
+    isOfType<T>(this: T, other: unknown): other is T;
+    isOfTypeStrict<T>(this: T, other: unknown): other is T;
 } & ErrorConstructor;
-type SigilError = GetInstance<typeof SigilError>;
+type SigilError = InstanceType<typeof SigilError>;
 
 /**
  * Configuration options for the Sigil library.
@@ -371,18 +322,6 @@ declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (v
  * @returns The same constructor value, with runtime metadata ensured.
  */
 declare function withSigil<S extends Function, L extends string = string>(Class: S, label?: L, opts?: SigilOptions): S;
-/**
- * Convenience helper that combine 'withSigil' and update 'SigilBrand'.
- *
- * @typeParam S - Constructor type (should be an ISigil).
- * @typeParam L - Label literal to attach.
- * @param Class - The constructor (class) to decorate and type.
- * @param label - Optional label string. If omitted, a random label is generated.
- * @param parent - Optional parent sigil constructor (type-only).
- * @param opts - Options object to override any global options if needed.
- * @returns The same constructor value, with runtime metadata ensured and typed as `TypedSigil<S,L,P>`.
- */
-declare function withSigilTyped<S extends Function, L extends string = string>(Class: S, label?: L, opts?: SigilOptions): TypedSigil<S, L>;
 
 /**
  * Runtime predicate that checks whether the provided value is a sigil constructor.
@@ -398,7 +337,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 GetInstance<ISigil>;
+declare function isSigilInstance(inst: unknown): inst is ISigilInstance;
 /**
  * Check whether the provided constructor was marked as a sigil base constructor.
  *
@@ -412,7 +351,7 @@ declare function isSigilBaseCtor(ctor: Function): ctor is ISigil;
  * @param inst - The instance to test.
  * @returns `true` if `inst` is an instance of a sigil base constructor.
  */
-declare function isSigilBaseInstance(inst: unknown): inst is GetInstance<ISigil>;
+declare function isSigilBaseInstance(inst: unknown): inst is ISigilInstance;
 /**
  * Returns whether the constructor has been explicitly decorated with `WithSigil`.
  *
@@ -442,16 +381,6 @@ declare function isInheritanceChecked(ctor: Function): boolean;
  */
 declare function Sigilify<B extends Constructor, L extends string>(Base: B, label?: L, opts?: SigilOptions): {
     new (...args: any[]): {
-        /**
-         * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
-         *
-         * - HAVE NO RUN-TIME VALUE (undefined)
-         * - Provides a *type-only* unique marker that makes instances nominally
-         *   distinct by label and allows propagation/merging of brand keys across inheritance.
-         */
-        readonly __SIGIL_BRAND__: {
-            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 type instance.
          *
@@ -462,7 +391,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
          * @param other - The object to test.
          * @returns `true` if `other` is the same instance of this type or a subtype.
          */
-        isOfType<T_1>(this: T_1, other: unknown): other is GetInstance<T_1>;
+        isOfType<T>(this: T, other: unknown): other is T;
         /**
          * Strict lineage check: compares the type label lineage arrays element-by-element.
          *
@@ -473,7 +402,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
          * @param other - The object to test.
          * @returns `true` if `other` has an identical lineage up to the length of this instance's lineage.
          */
-        isOfTypeStrict<T_1>(this: T_1, other: unknown): other is GetInstance<T_1>;
+        isOfTypeStrict<T>(this: T, other: unknown): other is T;
         /**
          * Returns the identity sigil label of this instance's constructor.
          *
@@ -498,25 +427,25 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
          * @returns A Readonly Set of labels representing the type lineage for O(1) membership tests.
          */
         getSigilLabelSet(): Readonly<Set<string>>;
+        /**
+         * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
+         *
+         * - HAVE NO RUN-TIME VALUE (undefined)
+         * - Provides a *type-only* unique marker that makes instances nominally
+         *   distinct by label and allows propagation/merging of brand keys across inheritance.
+         */
+        readonly [sigil]: {
+            Sigil: true;
+        } & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
     };
-    /**
-     * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
-     *
-     * - HAVE NO RUN-TIME VALUE (undefined)
-     * - Provides a *type-only* unique marker that makes instances nominally
-     *   distinct by label and allows propagation/merging of brand keys across inheritance.
-     */
-    readonly __SIGIL_BRAND__: Prettify<{
-        Sigil: true;
-    } & { [K in L]: true; }>;
     /**
      * Class-level identity label constant for this sigil constructor.
      */
-    get SigilLabel(): string;
+    get SigilLabel(): L;
     /**
      * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
      */
-    get SigilEffectiveLabel(): string;
+    get SigilEffectiveLabel(): L;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      *
@@ -551,7 +480,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
      * @param other - The object to test.
      * @returns `true` if `other` is an instance of this type or a subtype.
      */
-    isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
+    isOfType<T>(this: T, other: unknown): other is T;
     /**
      * Strict lineage check: compares the type label lineage arrays element-by-element.
      *
@@ -560,7 +489,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
      * @param other - The object to test.
      * @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
      */
-    isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
+    isOfTypeStrict<T>(this: T, other: unknown): other is T;
 } & B;
 /**
  * Mixin factory that augments an existing class with Sigil runtime metadata and helpers. Accept and return 'abstract' class.
@@ -573,16 +502,6 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
  * @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[]) => {
-    /**
-     * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
-     *
-     * - HAVE NO RUN-TIME VALUE (undefined)
-     * - Provides a *type-only* unique marker that makes instances nominally
-     *   distinct by label and allows propagation/merging of brand keys across inheritance.
-     */
-    readonly __SIGIL_BRAND__: {
-        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 type instance.
      *
@@ -593,7 +512,7 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @param other - The object to test.
      * @returns `true` if `other` is the same instance of this type or a subtype.
      */
-    isOfType<T_1>(this: T_1, other: unknown): other is GetInstance<T_1>;
+    isOfType<T>(this: T, other: unknown): other is T;
     /**
      * Strict lineage check: compares the type label lineage arrays element-by-element.
      *
@@ -604,7 +523,7 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @param other - The object to test.
      * @returns `true` if `other` has an identical lineage up to the length of this instance's lineage.
      */
-    isOfTypeStrict<T_1>(this: T_1, other: unknown): other is GetInstance<T_1>;
+    isOfTypeStrict<T>(this: T, other: unknown): other is T;
     /**
      * Returns the identity sigil label of this instance's constructor.
      *
@@ -629,7 +548,6 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @returns A Readonly Set of labels representing the type lineage for O(1) membership tests.
      */
     getSigilLabelSet(): Readonly<Set<string>>;
-}) & {
     /**
      * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
      *
@@ -637,17 +555,18 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * - Provides a *type-only* unique marker that makes instances nominally
      *   distinct by label and allows propagation/merging of brand keys across inheritance.
      */
-    readonly __SIGIL_BRAND__: Prettify<{
+    readonly [sigil]: {
         Sigil: true;
-    } & { [K in L]: 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(): string;
+    get SigilLabel(): L;
     /**
      * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
      */
-    get SigilEffectiveLabel(): string;
+    get SigilEffectiveLabel(): L;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      *
@@ -686,7 +605,7 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @param other - The object to test.
      * @returns `true` if `other` is an instance of this type or a subtype.
      */
-    isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
+    isOfType<T>(this: T, other: unknown): other is T;
     /**
      * Strict lineage check: compares the type label lineage arrays element-by-element.
      *
@@ -699,7 +618,7 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      * @param other - The object to test.
      * @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
      */
-    isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
+    isOfTypeStrict<T>(this: T, other: unknown): other is T;
 }) & B;
 
-export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, type SigilBrandOf, SigilError, type SigilOptions, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, updateSigilOptions, withSigil, withSigilTyped };
+export { DEFAULT_LABEL_REGEX, type ExtendSigil, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, SigilError, type SigilOf, type SigilOptions, Sigilify, SigilifyAbstract, WithSigil, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, sigil, updateSigilOptions, withSigil };