@vicin/sigil 3.3.0 → 4.0.0

package/README.md

@@ -1,20 +1,31 @@
 # Sigil
 
-[![npm version](https://img.shields.io/npm/v/@vicin/sigil.svg)](https://www.npmjs.com/package/@vicin/sigil) [![npm downloads](https://img.shields.io/npm/dm/@vicin/sigil.svg)](https://www.npmjs.com/package/@vicin/sigil) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue) [![Build](https://github.com/ZiadTaha62/sigil/actions/workflows/ci.yml/badge.svg)](https://github.com/ZiadTaha62/sigil/actions/workflows/ci.yml) ![bundle size](https://img.shields.io/bundlephobia/minzip/@vicin/sigil)
+[![npm version](https://img.shields.io/npm/v/@vicin/sigil.svg)](https://www.npmjs.com/package/@vicin/sigil) [![npm downloads](https://img.shields.io/npm/dm/@vicin/sigil.svg)](https://www.npmjs.com/package/@vicin/sigil) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue) [![Build](https://github.com/ZiadTaha62/vicin-packages/actions/workflows/ci.yml/badge.svg)](https://github.com/ZiadTaha62/vicin-packages/actions/workflows/ci.yml) ![bundle size](https://img.shields.io/bundlephobia/minzip/@vicin/sigil)
 
-> - 🎉 v3.0.0 is out! Happy coding! 😄💻
+> - 🎉 v4.0.0 is out! Happy coding! 😄💻
 > - 📄 **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
 
-`Sigil` gives you the power of **safe cross-bundle class instances checks** and **simple class nominal typing** if needed.
+**Sigil** — bulletproof class identity for large TypeScript projects.
 
-## Features
+Reliable `instanceof`-style checks that survive bundling, HMR, monorepos and realms + exact/subtype discrimination + lightweight nominal typing + and debug/log friendly labels/lineage.
 
-- ✅ **Drop-in `instanceof` replacement** that works across bundles, HMR and monorepos, Also add check for **exact class instance**
-- ✅ **Simple nominal typing** with just one line of code for each class (e.g., `UserId` vs. `PostId`)
-- ✅ **Tiny less than 1.6 KB minified and brotlied** measured using [size-limit](https://www.npmjs.com/package/size-limit)
-- ✅ **Performant as native instanceof** but with guaranteed checks
-- ✅ **Test coverage is 100%** to ensure that runtime remains consistent and predictable
-- ✅ **Safe with strict rules to ensure uniqueness of labels**, if duplicate label is passed error is thrown immediately
+## Why Sigil?
+
+- **Works when `instanceof` breaks** (multi-bundle, HMR, separate realms)
+- **Exact class match (`isExactInstance`)** — not just "inherits from"
+- **One-line nominal branding** (`declare [sigil]: ExtendSigil<…>`)
+- **Human-readable class IDs in logs & debugging** (`SigilLabel`/`SigilLineage`)
+- **Tiny (~0.9 kB brotli)**
+- **Fast (near native `instanceof` speed)**
+- **100% test coverage**
+
+## Limitations
+
+- **Identity is explicit and dependent on passed labels**, If same label is passed to two different classes `Sigil` will treat them as one
+- **Identity is updated with every new label passed only**, If you stopped passing labels to child classes their identity will stop at last passed label
+- **`Sigil` is not built for security**, identity can be forged
+
+Earlier versions of `Sigil` tried to solve these limitations, however it was not `100%` reliable, so we decided to make this package minimal and stable, while adding new features in future package `@vicin/sigil-extend`
 
 ---
 
@@ -24,7 +35,7 @@
   - [Install](#install)
   - [Basic usage](#basic-usage)
   - [Decorator pattern](#decorator-pattern)
-  - [HOF pattern](#hof-higher-order-function-pattern)
+  - [Function pattern](#function-pattern)
   - [Migration](#migration)
 - [Core concepts](#core-concepts)
   - [Terminology](#terminology)
@@ -37,6 +48,7 @@
 - [Minimal mode](#minimal-mode)
 - [Strict mode](#strict-mode)
 - [Hot module reload](#hot-module-reload)
+- [Edge cases](#edge-cases)
 - [Benchmarks](#benchmarks)
 - [Bundle Size](#bundle-size)
 - [Tests](#tests)
@@ -58,7 +70,9 @@ yarn add @vicin/sigil
 pnpm add @vicin/sigil
 ```
 
-Requires TypeScript 5.0+ for decorators; HOFs work on older versions. Node.js 18+ recommended.
+Requires TypeScript 5.0+ for decorators; attach functions work on older versions. Node.js 18+ recommended.
+
+> No tsconfig changes are needed as we use **Stage 3 decorators** which are supported by default in TypeScript 5.0+
 
 ### Basic usage
 
@@ -92,30 +106,28 @@ After opting into the `Sigil` contract, labels are passed to child classes to un
 
 ##### Decorator pattern
 
-Apply a label with the `@WithSigil` decorator:
+Apply a label with the `@AttachSigil` decorator:
 
 ```ts
-import { Sigil, WithSigil } from '@vicin/sigil';
+import { Sigil, AttachSigil } from '@vicin/sigil';
 
-@WithSigil('@myorg/mypkg.User')
+@AttachSigil('@myorg/mypkg.User')
 class User extends Sigil {}
 ```
 
-##### HOF (Higher-Order Function) pattern
+##### Function pattern
 
-Apply a label using `withSigil` HOF:
+Apply a label using `attachSigil` function:
 
 ```ts
-import { Sigil, withSigil } from '@vicin/sigil';
+import { Sigil, attachSigil } from '@vicin/sigil';
 
-class _User extends Sigil {}
-const User = withSigil(_User, '@myorg/mypkg.User');
+class User extends Sigil {}
+attachSigil(User, '@myorg/mypkg.User');
 ```
 
 ### Migration
 
-Migrating old code into `Sigil` can be done with extra couple lines of code only:
-
 1. Pass your base class to `Sigilify` mixin:
 
 ```ts
@@ -132,7 +144,7 @@ import { Sigil } from '@vicin/sigil';
 class MyBaseClass extends Sigil {} // <-- add 'extends Sigil' here
 ```
 
-Congratulations — you’ve opted into `Sigil` and you can start replacing `instanceof` with `isOfType()` / `isExactType()`, however there is more to add to your system, check [Core concepts](#core-concepts) for more.
+Congratulations — you’ve opted into `Sigil`, now you can start giving your classes identity by using `attachSigil` or `AttachSigil` helpers.
 
 ---
 
@@ -141,16 +153,15 @@ Congratulations — you’ve opted into `Sigil` and you can start replacing `ins
 ### Terminology
 
 - **Label**: An identity (string) such as `@scope/pkg.ClassName`, must be unique for each `Sigil` class otherwise error is thrown.
-- **EffectiveLabel:** A human-readable (string) such as `@scope/pkg.ClassName`, if no label is passed it inherit the last defined label.
-- **isOfType**: Takes object argument and check if this object is an instance of calling class or it's children. Can be called from class instances as well.
-- **isExactType**: Takes object argument and check if this object is an instance of calling class only. Can be called from class instances as well.
+- **isInstance**: Takes object argument and check if this object is an instance of calling class or it's children. Can be called from class instances as well.
+- **isExactInstance**: Takes object argument and check if this object is an instance of calling class only. Can be called from class instances as well.
 - **[sigil]**: TypeScript symbol marker for nominal types.
 
 ---
 
 ### Purpose and Origins
 
-Sigil addresses issues in large monorepos, HMR:
+Sigil addresses issues in large codebases and monorepos:
 
 - **Unreliable `instanceof`:** Bundling cause class redefinitions, breaking checks.
 
@@ -159,13 +170,13 @@ Sigil addresses issues in large monorepos, HMR:
 if (obj instanceof User) { ... }
 
 // With Sigil
-if (User.isOfType(obj)) { ... } // This still works even if User was bundled twice.
-if (User.isExactType(obj)) { ... } // Or check for exactly same constructor not its children
+if (User.isInstance(obj)) { ... } // This still works even if User was bundled twice.
+if (User.isExactInstance(obj)) { ... } // Or check for exactly same constructor not its children
 ```
 
-Also by utilizing unique passed labels it solve another problem in Domain-Driven Design (DDD):
+Also by utilizing unique passed labels it solves another problem in Domain-Driven Design (DDD):
 
-- **Manual Branding Overhead:** Custom identifiers lead to boilerplate and maintenance issues, `Sigil` add reliable inheritance-aware nominal branding with just one line of code.
+- **Manual Branding Overhead:** Custom identifiers lead to boilerplate and maintenance issues, `Sigil` adds reliable inheritance-aware nominal branding with just one line of code.
 
 ```ts
 import { sigil } from '@vicin/sigil';
@@ -178,46 +189,45 @@ type test1 = User extends Sigil ? true : false; // true
 type test2 = Sigil extends User ? true : false; // false
 ```
 
+- **Need for stable class id**: Most large projects implement their own labels (e.g. to be used in logs)
+
 ### Implementation Mechanics
 
 - **Runtime Contract:** Established via extending `Sigil` or using `Sigilify` mixin.
-- **Update metadata:** With each new child, use decorators or HOF to attach run-time metadata and `ExtendSigil` to update nominal type.
+- **Update metadata:** With each new child, use decorator (`AttachSigil`) or function (`attachSigil`) to attach run-time metadata, also use `ExtendSigil` on `[sigil]` field to update nominal type.
 
 ```ts
-import { Sigil, WithSigil, sigil, ExtendSigil } from '@vicin/sigil';
+import { Sigil, AttachSigil, sigil, ExtendSigil } from '@vicin/sigil';
 
-@WithSigil('@scope/package.MyClass') // <-- Run-time values update
+@AttachSigil('@scope/package.MyClass') // <-- Run-time values update
 class MyClass extends Sigil {
   declare [sigil]: ExtendSigil<'MyClass', Sigil>; // <-- compile-time type update
 }
 ```
 
-You can avoid decorators and use HOF if needed:
+You can avoid decorators and use normal functions if needed:
 
 ```ts
-import { Sigil, withSigil, sigil, ExtendSigil } from '@vicin/sigil';
+import { Sigil, attachSigil, sigil, ExtendSigil } from '@vicin/sigil';
 
-class _MyClass extends Sigil {
+class MyClass extends Sigil {
   declare [sigil]: ExtendSigil<'MyClass', Sigil>;
 }
 
-const MyClass = withSigil(_MyClass, '@scope/package.MyClass');
-type MyClass = InstanceType<typeof MyClass>;
+attachSigil(MyClass, '@scope/package.MyClass');
 ```
 
-Note that you can't use `InstanceType` on `private` or `protected` classes, however you can use `GetPrototype<T>` in such cases.
-
 ### Example
 
 ```ts
-import { Sigil, WithSigil } from '@vicin/sigil';
+import { Sigil, AttachSigil } from '@vicin/sigil';
 
-@WithSigil('@myorg/User')
+@AttachSigil('@myorg/User')
 class User extends Sigil {
   declare [sigil]: ExtendSigil<'User', Sigil>;
 }
 
-@WithSigil('@myorg/Admin')
+@AttachSigil('@myorg/Admin')
 class Admin extends User {
   declare [sigil]: ExtendSigil<'Admin', User>;
 }
@@ -226,92 +236,60 @@ const admin = new Admin();
 const user = new User();
 
 // Instanceof like behavior
-console.log(Admin.isOfType(admin)); // true
-console.log(Admin.isOfType(user)); // false
-console.log(User.isOfType(admin)); // true
-console.log(User.isOfType(user)); // true
+console.log(Admin.isInstance(admin)); // true
+console.log(Admin.isInstance(user)); // false
+console.log(User.isInstance(admin)); // true
+console.log(User.isInstance(user)); // true
 
 // Exact checks
-console.log(Admin.isExactType(admin)); // true
-console.log(Admin.isExactType(user)); // false
-console.log(User.isExactType(user)); // true
-console.log(User.isExactType(admin)); // false (Admin is child indeed but this checks for user specifically)
+console.log(Admin.isExactInstance(admin)); // true
+console.log(Admin.isExactInstance(user)); // false
+console.log(User.isExactInstance(user)); // true
+console.log(User.isExactInstance(admin)); // false (Admin is child indeed but this checks for user specifically)
 
 // Can use checks from instances
-console.log(admin.isOfType(user)); // false
-console.log(user.isOfType(admin)); // true
-console.log(admin.isExactType(user)); // false
-console.log(user.isExactType(admin)); // false
+console.log(admin.isInstance(user)); // false
+console.log(user.isInstance(admin)); // true
+console.log(admin.isExactInstance(user)); // false
+console.log(user.isExactInstance(admin)); // false
 
 // Type checks are nominal
 type test1 = Admin extends User ? true : false; // true
 type test2 = User extends Admin ? true : false; // false
 
 // Passed label must be unique (enforced by Sigil) so can be used as stable Id for class
-// Also 'SigilLabelLineage' and 'SigilLabelSet' are useful for logging & debugging
+// Also 'SigilLabelLineage' is useful for logging & debugging
 console.log(Admin.SigilLabel); // '@myorg/Admin'
-console.log(Admin.SigilEffectiveLabel); // '@myorg/Admin'
 console.log(Admin.SigilLabelLineage); // ['Sigil', '@myorg/User', '@myorg/Admin']
-console.log(Admin.SigilLabelSet); // Set(['Sigil', '@myorg/User', '@myorg/Admin'])
-console.log(admin.getSigilLabel()); // '@myorg/Admin'
-console.log(admin.getSigilEffectiveLabel()); // '@myorg/Admin'
-console.log(admin.getSigilLabelLineage()); // ['Sigil', '@myorg/User', '@myorg/Admin']
-console.log(admin.getSigilLabelSet()); // Set(['Sigil', '@myorg/User', '@myorg/Admin'])
+console.log(admin.SigilLabel); // '@myorg/Admin'
+console.log(admin.SigilLabelLineage); // ['Sigil', '@myorg/User', '@myorg/Admin']
 ```
 
 ### Errors & throws
 
 Run-time errors that can be thrown by `Sigil`:
 
-#### Double `Sigilify() / SigilifyAbstract()`
+#### Double Sigilify
 
 ```ts
 class A {}
-const B = Sigilify(A, 'A');
-const C = Sigilify(B, 'B'); // Throws: [Sigil Error] Class 'Sigilified' with label 'A' is already sigilified
-
-abstract class AbsA {}
-const AbsB = SigilifyAbstract(AbsA, 'AbsA');
-const AbsC = SigilifyAbstract(AbsB, 'AbsB'); // Throws: [Sigil Error] Class 'Sigilified' with label 'AbsA' is already sigilified
-```
-
-#### `@WithSigil() / withSigil()` on non-Sigil class
+Sigilify(Sigilify(A, 'A'), 'B'); // Throws: [Sigil Error] Class 'Sigilified' with label 'A' is already sigilified
 
-```ts
-@WithSigil('A')
-class A {} // Throws: [Sigil Error] 'WithSigil' decorator accept only Sigil classes but used on class 'A'
-
-withSigil(class A {}); // Throws: [Sigil Error] 'WithSigil' decorator accept only Sigil classes but used on class 'A'
-```
-
-#### Double `@WithSigil() / withSigil()`
-
-```ts
-@WithSigil('B')
-@WithSigil('A')
+@AttachSigil('B')
+@AttachSigil('A')
 class A extends Sigil {} // Throws: [Sigil Error] Class 'A' with label 'A' is already sigilified
 
-class _A extends Sigil {}
-withSigil(withSigil(_A, 'A'), 'B'); // Throws: [Sigil Error] Class 'A' with label 'A' is already sigilified
-```
-
-#### No label is passed with `autofillLabels: false`
-
-```ts
-updateSigilOptions({ autofillLabels: false });
-
 class A extends Sigil {}
-new A(); // Throws: [Sigil Error] Class 'A' is not sigilified, Make sure to sigilify all Sigil classes or set 'autofillLabels' to 'true'
+attachSigil(attachSigil(A, 'A'), 'B'); // Throws: [Sigil Error] Class 'A' with label 'A' is already sigilified
 ```
 
-#### Same label is passed twice to `Sigil`
+#### `@AttachSigil() / attachSigil()` on non-Sigil class
 
 ```ts
-@WithSigil('Label')
-class A extends Sigil {}
+@AttachSigil('A') // Throws: [Sigil Error] 'AttachSigil' decorator accept only Sigil classes but used on class 'A'
+class A {}
 
-@WithSigil('Label')
-class B extends Sigil {} // Throws: [Sigil Error] Passed label 'Label' to class 'B' is re-used, passed labels must be unique
+attachSigil(class A {}); // Throws: [Sigil Error] 'AttachSigil' function accept only Sigil classes but used on class 'A'
 ```
 
 #### Invalid label format
@@ -319,23 +297,18 @@ class B extends Sigil {} // Throws: [Sigil Error] Passed label 'Label' to class
 ```ts
 updateSigilOptions({ labelValidation: RECOMMENDED_LABEL_REGEX });
 
-@WithSigil('InvalidLabel')
+@AttachSigil('InvalidLabel')
 class A extends Sigil {} // Throws: [Sigil Error] Invalid Sigil label 'InvalidLabel'. Make sure that supplied label matches validation regex or function
 ```
 
-#### Using '@Sigil-auto' prefix
+#### Attach sigil to parent after child
 
 ```ts
-@WithSigil('@Sigil-auto:label')
-class X extends Sigil {} // Throws: '@Sigil-auto' is a prefex reserved by the library
-```
-
-#### Invalid options passed to `updateOptions`
+class Parent extends Sigil {}
+class Child extends Parent {}
 
-```ts
-updateSigilOptions({ autofillLabels: {} as any }); // Throws: 'updateSigilOptions.autofillLabels' must be boolean
-updateSigilOptions({ labelValidation: 123 as any }); // Throws: 'updateSigilOptions.labelValidation' must be null, function or RegExp
-updateSigilOptions({ skipLabelUniquenessCheck: 'str' as any }); // Throws: 'updateSigilOptions.skipLabelUniquenessCheck' must be boolean
+attachSigil(Child, 'Child');
+attachSigil(Parent, 'Parent'); // Throws: [Sigil Error] Class 'Parent' with label 'Sigil' is already sigilified
 ```
 
 ---
@@ -353,24 +326,21 @@ updateSigilOptions({ skipLabelUniquenessCheck: 'str' as any }); // Throws: 'upda
   - `SigilError`
 
 - **Decorator:**
-  - `WithSigil(label, opts?)`
+  - `AttachSigil(label, opts?)`
 
-- **HOFs:**
-  - `withSigil(Class, label, opts?)`
+- **Attach function:**
+  - `attachSigil(Class, label, opts?)`
 
 - **Helpers:**
   - `isSigilCtor(ctor)`
   - `isSigilInstance(inst)`
-  - `getSigilLabels()`
+  - `hasOwnSigil(ctor)`
 
 - **Options:**
   - `updateSigilOptions(opts)`
   - `RECOMMENDED_LABEL_REGEX`
 
 - **Types:**
-  - `ISigil<Label, ParentSigil?>`
-  - `ISigilStatic<Label, ParentSigil?>`
-  - `ISigilInstance<Label, ParentSigil?>`
   - `SigilOf<T>`
   - `ExtendSigil<Label, Parent>`
   - `GetPrototype<Class>`
@@ -382,12 +352,12 @@ updateSigilOptions({ skipLabelUniquenessCheck: 'str' as any }); // Throws: 'upda
 - `SigilError`: an `Error` class decorated with a `Sigil` so it can be identified at runtime.
 - `Sigilify(Base, label, opts?)`: mixin function that returns a new constructor with `Sigil` types and instance helpers.
 - `SigilifyAbstract(Base, label, opts?)`: Same as `Sigilify` but for abstract classes.
-- `WithSigil(label, opts?)`: class decorator that attaches `Sigil` metadata at declaration time.
-- `withSigil(Class, label, opts?)`: HOF that validates and decorates an existing class constructor.
+- `AttachSigil(label, opts?)`: class decorator that attaches `Sigil` metadata at declaration time.
+- `attachSigil(Class, label, opts?)`: function that validates and decorates an existing class constructor.
 - `isSigilCtor(value)`: `true` if `value` is a `Sigil` constructor.
 - `isSigilInstance(value)`: `true` if `value` is an instance of a `Sigil` constructor.
-- `getSigilLabels()`: Get `Sigil` labels registered.
-- `updateSigilOptions(opts)`: change global runtime options of `Sigil` library (e.g., `autofillLabels`).
+- `hasOwnSigil(ctor)`: `true` if new sigil label is attached to `ctor`
+- `updateSigilOptions(opts)`: change global runtime options of `Sigil` library (e.g., `labelValidation`).
 - `RECOMMENDED_LABEL_REGEX`: regex that ensures structure of `@scope/package.ClassName` to all labels, it's advised to use it as your `SigilOptions.labelValidation`
 
 ### Instance & static helpers provided by Sigilified constructors
@@ -395,20 +365,18 @@ updateSigilOptions({ skipLabelUniquenessCheck: 'str' as any }); // Throws: 'upda
 When a constructor is sigilified it will expose the following **static** getters/methods:
 
 - `SigilLabel` — the identity label string.
-- `SigilEffectiveLabel` — the human label string.
 - `SigilLabelLineage` — readonly array of labels representing parent → child for debugging.
-- `SigilLabelSet` — readonly `Set<string>` of sigil labels for debugging.
-- `isOfType(other)` — check if other is an instance of this constructor or its children.
-- `isExactType(other) `— check if other is an instance exactly this constructor.
+- `hasOwnSigil` — check if new sigil label is attached to this class.
+- `isInstance(other)` — check if other is an instance of this constructor or its children.
+- `isExactInstance(other) `— check if other is an instance exactly this constructor.
 
 Instances of sigilified classes expose instance helpers:
 
-- `getSigilLabel()` — returns the identity label.
-- `getSigilEffectiveLabel()` — returns the human label.
-- `getSigilLabelLineage()` — returns lineage array.
-- `getSigilLabelSet()` — returns readonly Set.
-- `isOfType(other)` — check if other is an instance of the same class or its children as this.
-- `isExactType(other) `— check if other is an instance exactly the same constructor.
+- `SigilLabel` — the identity label string.
+- `SigilLabelLineage` — readonly array of labels representing parent → child for debugging.
+- `hasOwnSigil` — check if new sigil label is attached to this class.
+- `isInstance(other)` — check if other is an instance of the same class or its children as this.
+- `isExactInstance(other) `— check if other is an instance exactly the same constructor.
 
 ---
 
@@ -420,64 +388,72 @@ Customize behavior globally at startup:
 import { updateSigilOptions } from '@vicin/sigil';
 
 updateSigilOptions({
-  autofillLabels: true, // Automatically label unlabeled subclasses
   labelValidation: null, // Function or regex, Enforce label format
-  skipLabelUniquenessCheck: false, // Skip uniqueness check for labels, should be used in HMR set-ups only
 });
 ```
 
-Values defined in previous example are defaults, per-class overrides available in mixin, decorators, and HOFs.
+Values defined in previous example are defaults, per-class overrides available in mixin and attach function / decorator.
 
 ---
 
-## Minimal mode
+## Edge cases
+
+### Attach sigil to parent after child
 
-By default `Sigil` works with minimal mode, You can ignore all decorators and HOFs and just make base class extend `Sigil`:
+When attaching `Sigil` labels to classes order from parent -> child must be respected
 
 ```ts
-import { Sigil, updateSigilOptions } from '@vicin/sigil';
+class Parent extends Sigil {}
+class Child extends Parent {}
 
-// No decorators or HOF needed to use 'isOfType' ('instanceof' replacement)
-class A extends Sigil {}
-class B extends A {}
-class C extends B {}
+attachSigil(Child, 'Child');
+attachSigil(Parent, 'Parent'); // Throws: [Sigil Error] Class 'Parent' with label 'Sigil' is already sigilified
 ```
 
-## Strict mode
+### Accessing Sigil `metadata` before running `attachSigil` function
 
-If you want to enforce passing a label to every class defined in your codebase, you can set `autofillLabels` to `false` at the start of app:
+If you didn't make sure that `attachSigil` runs right after class declaration and used one of `Sigil` methods this will occur:
 
 ```ts
-import { updateSigilOptions } from '@vicin/sigil';
+class A extends Sigil {}
 
-updateSigilOptions({ autofillLabels: false });
-```
+console.log(A.SigilLabel); // returns label of the parent (Sigil in our case)
 
-Now if you forgot to pass a label error is thrown at the moment you create class instance or use any of `Sigil` methods.
+attachSigil(A, 'A');
 
----
-
-## Hot module reload
+console.log(A.SigilLabel); // A
+```
 
-HMR can cause class re-definitions, which will throw in default `Sigil` set-up as same label will be passed multiple times triggering duplicate label error.
-To avoid this you can set global options to skip label uniqueness check at the start of app:
+To avoid this bug entirely you can use the return of `attachSigil` in your code so you are enforced to respect order:
 
 ```ts
-import { updateSigilOptions } from '@vicin/sigil';
+class _A extends Sigil {}
+
+const A = attachSigil(_A, 'A');
+type A = InstanceType<typeof A>;
 
-updateSigilOptions({ skipLabelUniquenessCheck: true });
+console.log(A.SigilLabel); // A
 ```
 
-But this can cause bugs if same label is used for two different classes as checks are disables globally.
-If you need more strict mode you can pass this options to the re-loaded class only:
+Note that you can't use `InstanceType` on `private` or `protected` classes, however you can use `GetPrototype<T>` in such cases.
+
+#### Static blocks & IIFE static initializer
+
+Stage 3 decorators (`AttachSigil`) and function (`attachSigil`) runs after IIFE and static blocks, so accessing `Sigil` metadata inside them should be avoided
 
 ```ts
-@WithSigil('HmrClassLabel', { skipLabelUniquenessCheck: true })
-class HmrClass extends Sigil {}
+@AttachSigil('A')
+class A extends Sigil {
+  static IIFE = (() => {
+    const label = A.SigilLabel; // returns label of the parent (Sigil in our case)
+  })();
+
+  static {
+    const label = this.SigilLabel; // returns label of the parent (Sigil in our case)
+  }
+}
 ```
 
-With this approach `skipLabelUniquenessCheck` affects only `HmrClass`, and if `HmrClassLabel` or any other label is re-used error is thrown immediately
-
 ---
 
 ## Benchmarks
@@ -486,68 +462,95 @@ Sigil is built for **real-world performance**. Below are the latest micro-benchm
 
 **Running Tests**
 
-To run benchmarks on your machine fetch source code from [github](https://github.com/ZiadTaha62/sigil) then:
+To run benchmarks on your machine fetch source code from [github](https://github.com/ZiadTaha62/vicin-packages) then:
 
 ```bash
-npm install
-npm run bench
+pnpm install
+pnpm run bench --filter @vicin/sigil
 ```
 
 ### 1. Runtime Type Checking
 
-| Depth | `instanceof` (per op) | `isOfType` (ctor) | `isOfType` (instance) | `isExactType` (ctor) | `isExactType` (instance) |
-| ----- | --------------------- | ----------------- | --------------------- | -------------------- | ------------------------ |
-| 0     | 0.000010 ms           | 0.000025 ms       | **0.000010 ms**       | 0.000027 ms          | 0.000012 ms              |
-| 3     | 0.000032 ms           | 0.000045 ms       | **0.000027 ms**       | 0.000038 ms          | **0.000025 ms**          |
-| 5     | 0.000034 ms           | 0.000046 ms       | **0.000028 ms**       | 0.000037 ms          | **0.000026 ms**          |
-| 10    | 0.000044 ms           | 0.000045 ms       | **0.000029 ms**       | 0.000038 ms          | **0.000027 ms**          |
-| 15    | 0.000058 ms           | 0.000063 ms       | **0.000051 ms**       | 0.000069 ms          | **0.000053 ms**          |
-
-> **Key takeaway**:  
-> `isOfType` & `isExactType` has **practically the same performance as native `instanceof`**, slightly **slower** on static calls and slightly **faster** on the instance side.
+| Test Name                  | Ops/sec (hz) | Mean (ms) | p99 (ms) | RME    | Samples   |
+| -------------------------- | ------------ | --------- | -------- | ------ | --------- |
+| **Depth 0**                |              |           |          |        |           |
+| instanceof                 | 11,986,628   | 0.0001    | 0.0002   | ±0.58% | 5,993,314 |
+| isInstance (Ctor)          | 8,848,040    | 0.0001    | 0.0003   | ±0.63% | 4,424,020 |
+| isInstance (instance)      | 9,246,878    | 0.0001    | 0.0002   | ±0.86% | 4,623,440 |
+| isExactInstance (Ctor)     | 5,114,916    | 0.0002    | 0.0003   | ±0.44% | 2,557,459 |
+| isExactInstance (instance) | 5,553,370    | 0.0002    | 0.0003   | ±0.41% | 2,776,686 |
+| **Depth 5**                |              |           |          |        |           |
+| instanceof                 | 8,399,150    | 0.0001    | 0.0002   | ±0.48% | 4,199,651 |
+| isInstance (Ctor)          | 7,385,890    | 0.0001    | 0.0003   | ±2.01% | 3,692,945 |
+| isInstance (instance)      | 7,862,474    | 0.0001    | 0.0003   | ±0.77% | 3,931,238 |
+| isExactInstance (Ctor)     | 4,433,700    | 0.0002    | 0.0004   | ±0.64% | 2,216,851 |
+| isExactInstance (instance) | 4,898,498    | 0.0002    | 0.0004   | ±0.34% | 2,449,249 |
+| **Depth 10**               |              |           |          |        |           |
+| instanceof                 | 7,144,486    | 0.0001    | 0.0003   | ±0.63% | 3,572,243 |
+| isInstance (Ctor)          | 7,165,920    | 0.0001    | 0.0003   | ±0.49% | 3,582,960 |
+| isInstance (instance)      | 7,834,056    | 0.0001    | 0.0003   | ±1.16% | 3,917,029 |
+| isExactInstance (Ctor)     | 4,292,578    | 0.0002    | 0.0004   | ±0.34% | 2,146,290 |
+| isExactInstance (instance) | 5,020,923    | 0.0002    | 0.0004   | ±0.28% | 2,510,462 |
+| **Depth 15**               |              |           |          |        |           |
+| instanceof                 | 7,116,266    | 0.0001    | 0.0002   | ±0.38% | 3,558,134 |
+| isInstance (Ctor)          | 6,308,498    | 0.0002    | 0.0003   | ±0.41% | 3,154,249 |
+| isInstance (instance)      | 6,403,126    | 0.0002    | 0.0003   | ±0.70% | 3,201,564 |
+| isExactInstance (Ctor)     | 3,678,280    | 0.0003    | 0.0005   | ±0.37% | 1,839,141 |
+| isExactInstance (instance) | 3,753,618    | 0.0003    | 0.0005   | ±0.39% | 1,876,810 |
+
+> **Key takeaway**:
+>
+> `isInstance` Efficiency: Demonstrates high parity with native instanceof, maintaining a minimal performance delta (approx. 15% overhead).
+> `isExactInstance` Cost-Benefit: While introducing a ~2x overhead compared to native operations, it remains performant in absolute terms. The throughput cost is a deliberate trade-off for the increased precision required for exact matching.
 
 ### 2. Class Definition & Instance Creation
 
-| Scenario                        | Definition (per class) | Instantiation (per instance) |
-| ------------------------------- | ---------------------- | ---------------------------- |
-| Empty plain class               | 0.0122 ms              | 0.00019 ms                   |
-| Empty Sigil class               | 0.0672 ms              | 0.00059 ms                   |
-| Small (5 props + 3 methods)     | 0.0172 ms              | 0.00327 ms                   |
-| Large (15 props + 10 methods)   | 0.0212 ms              | 0.00922 ms                   |
-| Large Sigil                     | 0.0780 ms              | 0.01177 ms                   |
-| Extended chain depth 5 – plain  | 0.0897 ms              | 0.01809 ms                   |
-| Extended chain depth 5 – Sigil  | 0.3978 ms              | 0.02020 ms                   |
-| Extended chain depth 10 – plain | 0.2042 ms              | 0.05759 ms                   |
-| Extended chain depth 10 – Sigil | 0.8127 ms              | 0.06675 ms                   |
+| Test Name                             | Ops/sec (hz)      | Mean (ms)        | p99 (ms)         | RME     | Samples   |
+| ------------------------------------- | ----------------- | ---------------- | ---------------- | ------- | --------- |
+| **Definition (Module Load Time)**     |                   |                  |                  |         |           |
+| Define Empty (Plain vs Sigil)         | 122,640 vs 13,154 | 0.0082 vs 0.0760 | 0.0206 vs 0.1413 | ±11.36% | 6,578     |
+| Define Small (Plain vs Sigil)         | 75,363 vs 12,003  | 0.0133 vs 0.0833 | 0.0267 vs 0.1596 | ±5.98%  | 6,002     |
+| Define Large (Plain vs Sigil)         | 53,392 vs 11,978  | 0.0187 vs 0.0835 | 0.0352 vs 0.1471 | ±6.13%  | 5,990     |
+| Define Depth 3 (Plain vs Sigil)       | 22,802 vs 5,205   | 0.0439 vs 0.1921 | 0.0850 vs 0.3139 | ±14.68% | 2,603     |
+| Define Depth 5 (Plain vs Sigil)       | 12,003 vs 3,369   | 0.0833 vs 0.2968 | 0.1864 vs 0.5488 | ±7.31%  | 1,685     |
+| Define Depth 10 (Plain vs Sigil)      | 5,477 vs 1,758    | 0.1826 vs 0.5685 | 0.3402 vs 1.1148 | ±9.62%  | 880       |
+| **Instantiation (Runtime/Hot Path)**  |                   |                  |                  |         |           |
+| Instantiate Empty (Plain vs Sigil)    | 12.0M vs 11.9M    | 0.0001 vs 0.0001 | 0.0002 vs 0.0002 | ±0.76%  | 5,999,555 |
+| Instantiate Small (Plain vs Sigil)    | 12.5M vs 11.4M    | 0.0001 vs 0.0001 | 0.0001 vs 0.0002 | ±0.89%  | 5,739,986 |
+| Instantiate Large (Plain vs Sigil)    | 12.4M vs 12.4M    | 0.0001 vs 0.0001 | 0.0002 vs 0.0001 | ±0.74%  | 6,205,306 |
+| Instantiate Depth 3 (Plain vs Sigil)  | 12.0M vs 12.1M    | 0.0001 vs 0.0001 | 0.0002 vs 0.0002 | ±1.01%  | 6,092,517 |
+| Instantiate Depth 5 (Plain vs Sigil)  | 9.09M vs 8.54M    | 0.0001 vs 0.0001 | 0.0002 vs 0.0003 | ±2.24%  | 4,272,328 |
+| Instantiate Depth 10 (Plain vs Sigil) | 2.87M vs 1.72M    | 0.0003 vs 0.0006 | 0.0008 vs 0.0011 | ±0.75%  | 862,564   |
 
 > **Key takeaways**:
 >
-> - Class definition is a **one-time cost** at module load time. Even at depth 10 the cost stays well under 1 ms per class.
-> - Instance creation adds a small fixed overhead of ~0.4–0.6 µs per object, which becomes completely negligible as your classes grow in size and complexity.
+> Front-Loaded Definition Overhead: Sigil introduces main overhead during the class definition phase (roughly 6x to 10x slower than plain classes). This is a one-time cost per class, typically occurring during module evaluation or registry setup.
+>
+> Runtime Performance Parity: Once the class is defined, Sigil achieves near-native instantiation throughput. For standard object creation, the delta is negligible, ensuring that the library does not bottleneck high-frequency allocation patterns.
+>
+> Scale Stability: The overhead of Sigil remains constant regardless of the number of properties or methods added (Small vs. Large). The definition speed for a "Small Sigil" and a "Large Sigil" is nearly identical (~12k hz), suggesting that the setup logic is O(1) relative to class member count.
 
 ---
 
 ## Bundle Size
 
-**Less than 1.6 KB (1.54 KB)** (minified + Brotli, including all dependencies)
+**Less than 1 KB (908 B)** (minified + Brotli, including all dependencies)
 
 This makes Sigil one of the smallest full-featured solutions for nominal typing + reliable runtime identity.
 
 **Running Tests**
 
-To verify bundle size fetch source code from [github](https://github.com/ZiadTaha62/sigil) then:
+To verify bundle size fetch source code from [github](https://github.com/ZiadTaha62/vicin-packages) then:
 
 ```bash
-npm install
-npm run size
+pnpm install
+pnpm run size --filter @vicin/sigil
 ```
 
 ---
 
 ## Tests
 
-Reliability is a core pillar of `Sigil`. The library is backed by a comprehensive suite of unit tests that cover everything from basic mixins to lazy evaluation.
-
 **Coverage Status**
 
 We maintain **100%** test coverage across the entire codebase to ensure that runtime metadata remains consistent and predictable.
@@ -559,21 +562,13 @@ We maintain **100%** test coverage across the entire codebase to ensure that run
 | Funcs  | 100%  |
 | Lines  | 100%  |
 
-**Key Test Areas**
-
-- **Mixins, Decorators & HOFs:** Validating `Sigilify`, `WithSigil` and `withSigil` behaviors.
-- **Sigil methods:** Ensuring `Sigil` class methods (e.g. `SigilLabel`, `getSigilLabel`) work as expected.
-- **Lazy Evaluation:** Ensuring metadata is attached before being accessed via `Sigil` methods.
-- **Lineage:** Verifying that `isOfType` and `isExactType` work across complex inheritance chains.
-- **Error Handling:** Strict validation for all errors and throws.
-
 **Running Tests**
 
-To run the test suite locally and generate a coverage report, fetch source code from [github](https://github.com/ZiadTaha62/sigil) then:
+To run the test suite locally and generate a coverage report, fetch source code from [github](https://github.com/ZiadTaha62/vicin-packages) then:
 
 ```bash
-npm install
-npm run test:unit
+pnpm install
+pnpm run test --filter @vicin/sigil
 ```
 
 ---