@vicin/sigil 1.2.5 → 1.2.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +14 -1
- package/dist/index.d.mts +148 -19
- package/dist/index.d.ts +148 -19
- package/dist/index.global.js +188 -0
- package/dist/index.global.js.map +1 -1
- package/dist/index.js +188 -0
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +188 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [1.2.7] - 2026-02-13
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- Support for `abstract` classes using `SigilifyAbstract` factory.
|
|
10
|
+
|
|
11
|
+
## [1.2.6] - 2026-02-11
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- Fixed type bug in 'isOfType'
|
|
16
|
+
|
|
5
17
|
## [1.2.5] - 2026-02-10
|
|
6
18
|
|
|
7
19
|
### Changed
|
package/README.md
CHANGED
|
@@ -86,6 +86,18 @@ class User extends Sigil {}
|
|
|
86
86
|
const MyClass = Sigilify(class {}, '@myorg/mypkg.MyClass');
|
|
87
87
|
```
|
|
88
88
|
|
|
89
|
+
If your class is marked with `abstract`:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
import { Sigil, SigilifyAbstract } from '@vicin/sigil';
|
|
93
|
+
|
|
94
|
+
// Using the pre-sigilified base class:
|
|
95
|
+
abstract class User extends Sigil {}
|
|
96
|
+
|
|
97
|
+
// Or use Sigilify when you want an ad-hoc class:
|
|
98
|
+
const MyClass = SigilifyAbstract(abstract class {}, '@myorg/mypkg.MyClass');
|
|
99
|
+
```
|
|
100
|
+
|
|
89
101
|
This adds runtime metadata to the constructor and allows you to use runtime helpers, see [API reference](#api-reference).
|
|
90
102
|
|
|
91
103
|
#### Extend `Sigil` classes
|
|
@@ -351,8 +363,9 @@ class X extends Sigil {
|
|
|
351
363
|
|
|
352
364
|
### Primary Exports
|
|
353
365
|
|
|
354
|
-
- **
|
|
366
|
+
- **Mixins:**
|
|
355
367
|
- `Sigilify(Base, label?, opts?)`
|
|
368
|
+
- `SigilifyAbstract(Base, label?, opts?)`
|
|
356
369
|
|
|
357
370
|
- **Classes:**
|
|
358
371
|
- `Sigil`
|
package/dist/index.d.mts
CHANGED
|
@@ -400,14 +400,10 @@ interface ISigilInstance<L extends string = string, P extends Function = never>
|
|
|
400
400
|
/**
|
|
401
401
|
* Combined constructor + static interface for a sigil class.
|
|
402
402
|
*
|
|
403
|
-
* This composes the instance-side shape (Constructor<ISigilInstance<L>>) with
|
|
404
|
-
* the static-side interface (ISigilStatic<L>), matching the runtime shape added
|
|
405
|
-
* by `Sigilify`.
|
|
406
|
-
*
|
|
407
403
|
* @template L - Narrow string literal type for the label.
|
|
408
404
|
* @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
|
|
409
405
|
*/
|
|
410
|
-
type ISigil<L extends string = string, P extends Function = never> =
|
|
406
|
+
type ISigil<L extends string = string, P extends Function = never> = ConstructorAbstract<ISigilInstance<L, P>> & ISigilStatic<L, P>;
|
|
411
407
|
/** -----------------------------------------
|
|
412
408
|
* HOF pattern types
|
|
413
409
|
* ----------------------------------------- */
|
|
@@ -418,7 +414,7 @@ type ISigil<L extends string = string, P extends Function = never> = Constructor
|
|
|
418
414
|
* @template S - The original Untyped Sigil constructor type being augmented.
|
|
419
415
|
* @template L - The new label literal to associate with the resulting constructor.
|
|
420
416
|
*/
|
|
421
|
-
type TypedSigil<S extends Function, L extends string = string> = S & AppendLabel<L> &
|
|
417
|
+
type TypedSigil<S extends Function, L extends string = string> = S & AppendLabel<L> & ConstructorAbstract<AppendLabel<L>>;
|
|
422
418
|
/**
|
|
423
419
|
* Generic helper extract instance of the class even in protected and private constructors.
|
|
424
420
|
*/
|
|
@@ -468,6 +464,16 @@ type SigilBrandOf<S> = IfNever<S extends {
|
|
|
468
464
|
* @template P - Parameter tuple type for the constructor.
|
|
469
465
|
*/
|
|
470
466
|
type Constructor<T = object, P extends any[] = any[]> = new (...args: P) => T;
|
|
467
|
+
/**
|
|
468
|
+
* Generic type for class constructors used by the Sigil utilities. for 'abstract classes'.
|
|
469
|
+
*
|
|
470
|
+
* - `T` is the instance type produced by the constructor.
|
|
471
|
+
* - `P` is the tuple of parameter types accepted by the constructor.
|
|
472
|
+
*
|
|
473
|
+
* @template T - Instance type produced by the constructor (defaults to `object`).
|
|
474
|
+
* @template P - Parameter tuple type for the constructor.
|
|
475
|
+
*/
|
|
476
|
+
type ConstructorAbstract<T = object, P extends any[] = any[]> = abstract new (...args: P) => T;
|
|
471
477
|
/** Helper type to prettify value */
|
|
472
478
|
type Prettify<T> = {
|
|
473
479
|
[K in keyof T]: T[K];
|
|
@@ -503,8 +509,8 @@ declare const Sigil: {
|
|
|
503
509
|
get SigilTypeLineage(): readonly symbol[];
|
|
504
510
|
get SigilTypeSet(): Readonly<Set<symbol>>;
|
|
505
511
|
isSigilified(obj: unknown): obj is ISigil;
|
|
506
|
-
isOfType<T
|
|
507
|
-
isOfTypeStrict<T
|
|
512
|
+
isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
513
|
+
isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
508
514
|
} & {
|
|
509
515
|
new (): {};
|
|
510
516
|
};
|
|
@@ -536,8 +542,8 @@ declare const SigilError: {
|
|
|
536
542
|
get SigilTypeLineage(): readonly symbol[];
|
|
537
543
|
get SigilTypeSet(): Readonly<Set<symbol>>;
|
|
538
544
|
isSigilified(obj: unknown): obj is ISigil;
|
|
539
|
-
isOfType<T
|
|
540
|
-
isOfTypeStrict<T
|
|
545
|
+
isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
546
|
+
isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
541
547
|
} & ErrorConstructor;
|
|
542
548
|
type SigilError = InstanceType<typeof SigilError>;
|
|
543
549
|
|
|
@@ -684,16 +690,13 @@ declare function isInheritanceChecked(ctor: Function): boolean;
|
|
|
684
690
|
|
|
685
691
|
/**
|
|
686
692
|
* Mixin factory that augments an existing class with Sigil runtime metadata and
|
|
687
|
-
* helpers.
|
|
693
|
+
* helpers.
|
|
694
|
+
*
|
|
695
|
+
* The returned class:
|
|
688
696
|
* - registers a stable symbol for the provided `label` (via `WithSigil`)
|
|
689
697
|
* - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
|
|
690
698
|
* - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
|
|
691
699
|
*
|
|
692
|
-
* Notes:
|
|
693
|
-
* - Uses `Symbol.for(label)` internally so symbols are stable across bundles/realms
|
|
694
|
-
* that share the global symbol registry.
|
|
695
|
-
* - Throws if `Base` is already a sigil constructor.
|
|
696
|
-
*
|
|
697
700
|
* @param Base - The base constructor to extend.
|
|
698
701
|
* @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
|
|
699
702
|
* If not passed a random label is generated instead.
|
|
@@ -797,7 +800,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
|
|
|
797
800
|
* @param other - The object to test.
|
|
798
801
|
* @returns `true` if `other` is an instance of this type or a subtype.
|
|
799
802
|
*/
|
|
800
|
-
isOfType<T
|
|
803
|
+
isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
801
804
|
/**
|
|
802
805
|
* Strict lineage check: compares the type symbol lineage arrays element-by-element.
|
|
803
806
|
*
|
|
@@ -810,7 +813,133 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
|
|
|
810
813
|
* @param other - The object to test.
|
|
811
814
|
* @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
|
|
812
815
|
*/
|
|
813
|
-
isOfTypeStrict<T
|
|
816
|
+
isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
814
817
|
} & B;
|
|
818
|
+
/**
|
|
819
|
+
* Mixin factory that augments an existing class with Sigil runtime metadata and
|
|
820
|
+
* helpers. Accept and return 'abstract' class.
|
|
821
|
+
*
|
|
822
|
+
* The returned class:
|
|
823
|
+
* - registers a stable symbol for the provided `label` (via `WithSigil`)
|
|
824
|
+
* - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
|
|
825
|
+
* - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
|
|
826
|
+
*
|
|
827
|
+
* @param Base - The base constructor to extend.
|
|
828
|
+
* @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
|
|
829
|
+
* If not passed a random label is generated instead.
|
|
830
|
+
* @param opts - Options object to override any global options if needed.
|
|
831
|
+
* @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
|
|
832
|
+
* @throws Error if `Base` is already sigilized.
|
|
833
|
+
*/
|
|
834
|
+
declare function SigilifyAbstract<B extends ConstructorAbstract, L extends string>(Base: B, label?: L, opts?: SigilOptions): ((abstract new (...args: any[]) => {
|
|
835
|
+
/**
|
|
836
|
+
* Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
|
|
837
|
+
*
|
|
838
|
+
* - HAVE NO RUN-TIME VALUE (undefined)
|
|
839
|
+
* - Provides a *type-only* unique marker that makes instances nominally
|
|
840
|
+
* distinct by label and allows propagation/merging of brand keys across inheritance.
|
|
841
|
+
*/
|
|
842
|
+
readonly __SIGIL_BRAND__: {
|
|
843
|
+
Sigil: true;
|
|
844
|
+
} & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
|
|
845
|
+
/**
|
|
846
|
+
* Returns the human-readable sigil label of this instance's constructor.
|
|
847
|
+
*
|
|
848
|
+
* @returns The label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' in DEV when constructor is missing.
|
|
849
|
+
*/
|
|
850
|
+
getSigilLabel(): string;
|
|
851
|
+
/**
|
|
852
|
+
* Returns the runtime sigil type symbol of this instance's constructor.
|
|
853
|
+
*
|
|
854
|
+
* @returns The symbol that identifies this type at runtime.
|
|
855
|
+
*/
|
|
856
|
+
getSigilType(): symbol;
|
|
857
|
+
/**
|
|
858
|
+
* Returns a copy of the sigil type symbol lineage for this instance's constructor.
|
|
859
|
+
*
|
|
860
|
+
* @returns readonly array of symbols representing the type lineage.
|
|
861
|
+
*/
|
|
862
|
+
getSigilTypeLineage(): readonly symbol[];
|
|
863
|
+
/**
|
|
864
|
+
* Returns a readonly copy of the sigil type symbol set for this instance's constructor.
|
|
865
|
+
*
|
|
866
|
+
* @returns A Readonly Set of symbols representing the type lineage for O(1) membership tests.
|
|
867
|
+
*/
|
|
868
|
+
getSigilTypeSet(): Readonly<Set<symbol>>;
|
|
869
|
+
}) & {
|
|
870
|
+
/**
|
|
871
|
+
* Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
|
|
872
|
+
*
|
|
873
|
+
* - HAVE NO RUN-TIME VALUE (undefined)
|
|
874
|
+
* - Provides a *type-only* unique marker that makes instances nominally
|
|
875
|
+
* distinct by label and allows propagation/merging of brand keys across inheritance.
|
|
876
|
+
*/
|
|
877
|
+
readonly __SIGIL_BRAND__: Prettify<{
|
|
878
|
+
Sigil: true;
|
|
879
|
+
} & { [K in L]: true; }>;
|
|
880
|
+
/**
|
|
881
|
+
* Class-level human-readable label constant for this sigil constructor.
|
|
882
|
+
*/
|
|
883
|
+
get SigilLabel(): string;
|
|
884
|
+
/**
|
|
885
|
+
* Class-level unique runtime symbol used as the type identifier.
|
|
886
|
+
*
|
|
887
|
+
* This symbol is created with `Symbol.for(label)` during decoration so it is
|
|
888
|
+
* stable across realms that share the same global symbol registry.
|
|
889
|
+
*/
|
|
890
|
+
get SigilType(): symbol;
|
|
891
|
+
/**
|
|
892
|
+
* Copy of the linearized sigil type symbol chain for the current constructor.
|
|
893
|
+
*
|
|
894
|
+
* Useful for debugging and performing strict lineage comparisons.
|
|
895
|
+
*
|
|
896
|
+
* @returns An array of symbols representing parent → child type symbols.
|
|
897
|
+
*/
|
|
898
|
+
get SigilTypeLineage(): readonly symbol[];
|
|
899
|
+
/**
|
|
900
|
+
* Copy of the sigil type symbol set for the current constructor.
|
|
901
|
+
*
|
|
902
|
+
* Useful for quick membership checks (O(1) lookups) and debugging.
|
|
903
|
+
*
|
|
904
|
+
* @returns A Readonly Set of symbols that represent the type lineage.
|
|
905
|
+
*/
|
|
906
|
+
get SigilTypeSet(): Readonly<Set<symbol>>;
|
|
907
|
+
/**
|
|
908
|
+
* Runtime predicate indicating whether `obj` is an instance produced by a sigil class.
|
|
909
|
+
*
|
|
910
|
+
* @param obj - The value to test.
|
|
911
|
+
* @returns `true` if `obj` is a sigil instance.
|
|
912
|
+
*/
|
|
913
|
+
isSigilified(obj: unknown): obj is ISigil;
|
|
914
|
+
/**
|
|
915
|
+
* Check whether `other` is (or inherits from) the type represented by the calling constructor.
|
|
916
|
+
*
|
|
917
|
+
* Implementation detail:
|
|
918
|
+
* - Uses the other instance's `__TYPE_SET__` for O(1) membership test.
|
|
919
|
+
* - O(1) and reliable as long as `OPTIONS.skipLabelInheritanceCheck` is `false`.
|
|
920
|
+
*
|
|
921
|
+
* This replaces `instanceof` so that checks remain valid across bundles/realms
|
|
922
|
+
* and when subclassing.
|
|
923
|
+
*
|
|
924
|
+
* @typeParam T - The calling constructor type (narrowing the returned instance type).
|
|
925
|
+
* @param this - The constructor performing the check.
|
|
926
|
+
* @param other - The object to test.
|
|
927
|
+
* @returns `true` if `other` is an instance of this type or a subtype.
|
|
928
|
+
*/
|
|
929
|
+
isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
930
|
+
/**
|
|
931
|
+
* Strict lineage check: compares the type symbol lineage arrays element-by-element.
|
|
932
|
+
*
|
|
933
|
+
* Implementation detail:
|
|
934
|
+
* - Works in O(n) time where n is the depth of the lineage.
|
|
935
|
+
* - Reliable when `OPTIONS.skipLabelInheritanceCheck` is `false`.
|
|
936
|
+
*
|
|
937
|
+
* @typeParam T - The calling constructor type.
|
|
938
|
+
* @param this - The constructor performing the check.
|
|
939
|
+
* @param other - The object to test.
|
|
940
|
+
* @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
|
|
941
|
+
*/
|
|
942
|
+
isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
943
|
+
}) & B;
|
|
815
944
|
|
|
816
|
-
export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, type TypedSigil, type UpdateSigilBrand, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };
|
|
945
|
+
export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };
|
package/dist/index.d.ts
CHANGED
|
@@ -400,14 +400,10 @@ interface ISigilInstance<L extends string = string, P extends Function = never>
|
|
|
400
400
|
/**
|
|
401
401
|
* Combined constructor + static interface for a sigil class.
|
|
402
402
|
*
|
|
403
|
-
* This composes the instance-side shape (Constructor<ISigilInstance<L>>) with
|
|
404
|
-
* the static-side interface (ISigilStatic<L>), matching the runtime shape added
|
|
405
|
-
* by `Sigilify`.
|
|
406
|
-
*
|
|
407
403
|
* @template L - Narrow string literal type for the label.
|
|
408
404
|
* @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
|
|
409
405
|
*/
|
|
410
|
-
type ISigil<L extends string = string, P extends Function = never> =
|
|
406
|
+
type ISigil<L extends string = string, P extends Function = never> = ConstructorAbstract<ISigilInstance<L, P>> & ISigilStatic<L, P>;
|
|
411
407
|
/** -----------------------------------------
|
|
412
408
|
* HOF pattern types
|
|
413
409
|
* ----------------------------------------- */
|
|
@@ -418,7 +414,7 @@ type ISigil<L extends string = string, P extends Function = never> = Constructor
|
|
|
418
414
|
* @template S - The original Untyped Sigil constructor type being augmented.
|
|
419
415
|
* @template L - The new label literal to associate with the resulting constructor.
|
|
420
416
|
*/
|
|
421
|
-
type TypedSigil<S extends Function, L extends string = string> = S & AppendLabel<L> &
|
|
417
|
+
type TypedSigil<S extends Function, L extends string = string> = S & AppendLabel<L> & ConstructorAbstract<AppendLabel<L>>;
|
|
422
418
|
/**
|
|
423
419
|
* Generic helper extract instance of the class even in protected and private constructors.
|
|
424
420
|
*/
|
|
@@ -468,6 +464,16 @@ type SigilBrandOf<S> = IfNever<S extends {
|
|
|
468
464
|
* @template P - Parameter tuple type for the constructor.
|
|
469
465
|
*/
|
|
470
466
|
type Constructor<T = object, P extends any[] = any[]> = new (...args: P) => T;
|
|
467
|
+
/**
|
|
468
|
+
* Generic type for class constructors used by the Sigil utilities. for 'abstract classes'.
|
|
469
|
+
*
|
|
470
|
+
* - `T` is the instance type produced by the constructor.
|
|
471
|
+
* - `P` is the tuple of parameter types accepted by the constructor.
|
|
472
|
+
*
|
|
473
|
+
* @template T - Instance type produced by the constructor (defaults to `object`).
|
|
474
|
+
* @template P - Parameter tuple type for the constructor.
|
|
475
|
+
*/
|
|
476
|
+
type ConstructorAbstract<T = object, P extends any[] = any[]> = abstract new (...args: P) => T;
|
|
471
477
|
/** Helper type to prettify value */
|
|
472
478
|
type Prettify<T> = {
|
|
473
479
|
[K in keyof T]: T[K];
|
|
@@ -503,8 +509,8 @@ declare const Sigil: {
|
|
|
503
509
|
get SigilTypeLineage(): readonly symbol[];
|
|
504
510
|
get SigilTypeSet(): Readonly<Set<symbol>>;
|
|
505
511
|
isSigilified(obj: unknown): obj is ISigil;
|
|
506
|
-
isOfType<T
|
|
507
|
-
isOfTypeStrict<T
|
|
512
|
+
isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
513
|
+
isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
508
514
|
} & {
|
|
509
515
|
new (): {};
|
|
510
516
|
};
|
|
@@ -536,8 +542,8 @@ declare const SigilError: {
|
|
|
536
542
|
get SigilTypeLineage(): readonly symbol[];
|
|
537
543
|
get SigilTypeSet(): Readonly<Set<symbol>>;
|
|
538
544
|
isSigilified(obj: unknown): obj is ISigil;
|
|
539
|
-
isOfType<T
|
|
540
|
-
isOfTypeStrict<T
|
|
545
|
+
isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
546
|
+
isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
541
547
|
} & ErrorConstructor;
|
|
542
548
|
type SigilError = InstanceType<typeof SigilError>;
|
|
543
549
|
|
|
@@ -684,16 +690,13 @@ declare function isInheritanceChecked(ctor: Function): boolean;
|
|
|
684
690
|
|
|
685
691
|
/**
|
|
686
692
|
* Mixin factory that augments an existing class with Sigil runtime metadata and
|
|
687
|
-
* helpers.
|
|
693
|
+
* helpers.
|
|
694
|
+
*
|
|
695
|
+
* The returned class:
|
|
688
696
|
* - registers a stable symbol for the provided `label` (via `WithSigil`)
|
|
689
697
|
* - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
|
|
690
698
|
* - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
|
|
691
699
|
*
|
|
692
|
-
* Notes:
|
|
693
|
-
* - Uses `Symbol.for(label)` internally so symbols are stable across bundles/realms
|
|
694
|
-
* that share the global symbol registry.
|
|
695
|
-
* - Throws if `Base` is already a sigil constructor.
|
|
696
|
-
*
|
|
697
700
|
* @param Base - The base constructor to extend.
|
|
698
701
|
* @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
|
|
699
702
|
* If not passed a random label is generated instead.
|
|
@@ -797,7 +800,7 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
|
|
|
797
800
|
* @param other - The object to test.
|
|
798
801
|
* @returns `true` if `other` is an instance of this type or a subtype.
|
|
799
802
|
*/
|
|
800
|
-
isOfType<T
|
|
803
|
+
isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
801
804
|
/**
|
|
802
805
|
* Strict lineage check: compares the type symbol lineage arrays element-by-element.
|
|
803
806
|
*
|
|
@@ -810,7 +813,133 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
|
|
|
810
813
|
* @param other - The object to test.
|
|
811
814
|
* @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
|
|
812
815
|
*/
|
|
813
|
-
isOfTypeStrict<T
|
|
816
|
+
isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
814
817
|
} & B;
|
|
818
|
+
/**
|
|
819
|
+
* Mixin factory that augments an existing class with Sigil runtime metadata and
|
|
820
|
+
* helpers. Accept and return 'abstract' class.
|
|
821
|
+
*
|
|
822
|
+
* The returned class:
|
|
823
|
+
* - registers a stable symbol for the provided `label` (via `WithSigil`)
|
|
824
|
+
* - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
|
|
825
|
+
* - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
|
|
826
|
+
*
|
|
827
|
+
* @param Base - The base constructor to extend.
|
|
828
|
+
* @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
|
|
829
|
+
* If not passed a random label is generated instead.
|
|
830
|
+
* @param opts - Options object to override any global options if needed.
|
|
831
|
+
* @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
|
|
832
|
+
* @throws Error if `Base` is already sigilized.
|
|
833
|
+
*/
|
|
834
|
+
declare function SigilifyAbstract<B extends ConstructorAbstract, L extends string>(Base: B, label?: L, opts?: SigilOptions): ((abstract new (...args: any[]) => {
|
|
835
|
+
/**
|
|
836
|
+
* Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
|
|
837
|
+
*
|
|
838
|
+
* - HAVE NO RUN-TIME VALUE (undefined)
|
|
839
|
+
* - Provides a *type-only* unique marker that makes instances nominally
|
|
840
|
+
* distinct by label and allows propagation/merging of brand keys across inheritance.
|
|
841
|
+
*/
|
|
842
|
+
readonly __SIGIL_BRAND__: {
|
|
843
|
+
Sigil: true;
|
|
844
|
+
} & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
|
|
845
|
+
/**
|
|
846
|
+
* Returns the human-readable sigil label of this instance's constructor.
|
|
847
|
+
*
|
|
848
|
+
* @returns The label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' in DEV when constructor is missing.
|
|
849
|
+
*/
|
|
850
|
+
getSigilLabel(): string;
|
|
851
|
+
/**
|
|
852
|
+
* Returns the runtime sigil type symbol of this instance's constructor.
|
|
853
|
+
*
|
|
854
|
+
* @returns The symbol that identifies this type at runtime.
|
|
855
|
+
*/
|
|
856
|
+
getSigilType(): symbol;
|
|
857
|
+
/**
|
|
858
|
+
* Returns a copy of the sigil type symbol lineage for this instance's constructor.
|
|
859
|
+
*
|
|
860
|
+
* @returns readonly array of symbols representing the type lineage.
|
|
861
|
+
*/
|
|
862
|
+
getSigilTypeLineage(): readonly symbol[];
|
|
863
|
+
/**
|
|
864
|
+
* Returns a readonly copy of the sigil type symbol set for this instance's constructor.
|
|
865
|
+
*
|
|
866
|
+
* @returns A Readonly Set of symbols representing the type lineage for O(1) membership tests.
|
|
867
|
+
*/
|
|
868
|
+
getSigilTypeSet(): Readonly<Set<symbol>>;
|
|
869
|
+
}) & {
|
|
870
|
+
/**
|
|
871
|
+
* Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
|
|
872
|
+
*
|
|
873
|
+
* - HAVE NO RUN-TIME VALUE (undefined)
|
|
874
|
+
* - Provides a *type-only* unique marker that makes instances nominally
|
|
875
|
+
* distinct by label and allows propagation/merging of brand keys across inheritance.
|
|
876
|
+
*/
|
|
877
|
+
readonly __SIGIL_BRAND__: Prettify<{
|
|
878
|
+
Sigil: true;
|
|
879
|
+
} & { [K in L]: true; }>;
|
|
880
|
+
/**
|
|
881
|
+
* Class-level human-readable label constant for this sigil constructor.
|
|
882
|
+
*/
|
|
883
|
+
get SigilLabel(): string;
|
|
884
|
+
/**
|
|
885
|
+
* Class-level unique runtime symbol used as the type identifier.
|
|
886
|
+
*
|
|
887
|
+
* This symbol is created with `Symbol.for(label)` during decoration so it is
|
|
888
|
+
* stable across realms that share the same global symbol registry.
|
|
889
|
+
*/
|
|
890
|
+
get SigilType(): symbol;
|
|
891
|
+
/**
|
|
892
|
+
* Copy of the linearized sigil type symbol chain for the current constructor.
|
|
893
|
+
*
|
|
894
|
+
* Useful for debugging and performing strict lineage comparisons.
|
|
895
|
+
*
|
|
896
|
+
* @returns An array of symbols representing parent → child type symbols.
|
|
897
|
+
*/
|
|
898
|
+
get SigilTypeLineage(): readonly symbol[];
|
|
899
|
+
/**
|
|
900
|
+
* Copy of the sigil type symbol set for the current constructor.
|
|
901
|
+
*
|
|
902
|
+
* Useful for quick membership checks (O(1) lookups) and debugging.
|
|
903
|
+
*
|
|
904
|
+
* @returns A Readonly Set of symbols that represent the type lineage.
|
|
905
|
+
*/
|
|
906
|
+
get SigilTypeSet(): Readonly<Set<symbol>>;
|
|
907
|
+
/**
|
|
908
|
+
* Runtime predicate indicating whether `obj` is an instance produced by a sigil class.
|
|
909
|
+
*
|
|
910
|
+
* @param obj - The value to test.
|
|
911
|
+
* @returns `true` if `obj` is a sigil instance.
|
|
912
|
+
*/
|
|
913
|
+
isSigilified(obj: unknown): obj is ISigil;
|
|
914
|
+
/**
|
|
915
|
+
* Check whether `other` is (or inherits from) the type represented by the calling constructor.
|
|
916
|
+
*
|
|
917
|
+
* Implementation detail:
|
|
918
|
+
* - Uses the other instance's `__TYPE_SET__` for O(1) membership test.
|
|
919
|
+
* - O(1) and reliable as long as `OPTIONS.skipLabelInheritanceCheck` is `false`.
|
|
920
|
+
*
|
|
921
|
+
* This replaces `instanceof` so that checks remain valid across bundles/realms
|
|
922
|
+
* and when subclassing.
|
|
923
|
+
*
|
|
924
|
+
* @typeParam T - The calling constructor type (narrowing the returned instance type).
|
|
925
|
+
* @param this - The constructor performing the check.
|
|
926
|
+
* @param other - The object to test.
|
|
927
|
+
* @returns `true` if `other` is an instance of this type or a subtype.
|
|
928
|
+
*/
|
|
929
|
+
isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
930
|
+
/**
|
|
931
|
+
* Strict lineage check: compares the type symbol lineage arrays element-by-element.
|
|
932
|
+
*
|
|
933
|
+
* Implementation detail:
|
|
934
|
+
* - Works in O(n) time where n is the depth of the lineage.
|
|
935
|
+
* - Reliable when `OPTIONS.skipLabelInheritanceCheck` is `false`.
|
|
936
|
+
*
|
|
937
|
+
* @typeParam T - The calling constructor type.
|
|
938
|
+
* @param this - The constructor performing the check.
|
|
939
|
+
* @param other - The object to test.
|
|
940
|
+
* @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
|
|
941
|
+
*/
|
|
942
|
+
isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
|
|
943
|
+
}) & B;
|
|
815
944
|
|
|
816
|
-
export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, type TypedSigil, type UpdateSigilBrand, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };
|
|
945
|
+
export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };
|