@vicin/sigil 3.4.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, and adds an **exact-class-instance check**
-- ✅ **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`
 
 ---
 
@@ -115,12 +126,8 @@ class User extends Sigil {}
 attachSigil(User, '@myorg/mypkg.User');
 ```
 
-> Note: Function pattern is susceptible to some [Edge case subtle pitfalls](#edge-cases) if not used appropriately, so we advise to use decorator pattern
-
 ### 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
@@ -137,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.
 
 ---
 
@@ -146,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.
 
@@ -164,8 +170,8 @@ 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 solves another problem in Domain-Driven Design (DDD):
@@ -183,6 +189,8 @@ 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.
@@ -228,22 +236,22 @@ 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
@@ -252,11 +260,9 @@ 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' 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.getSigilLabel()); // '@myorg/Admin'
-console.log(admin.getSigilEffectiveLabel()); // '@myorg/Admin'
-console.log(admin.getSigilLabelLineage()); // ['Sigil', '@myorg/User', '@myorg/Admin']
+console.log(admin.SigilLabel); // '@myorg/Admin'
+console.log(admin.SigilLabelLineage); // ['Sigil', '@myorg/User', '@myorg/Admin']
 ```
 
 ### Errors & throws
@@ -286,25 +292,6 @@ class A {}
 attachSigil(class A {}); // Throws: [Sigil Error] 'AttachSigil' function accept only Sigil classes but used on class 'A'
 ```
 
-#### 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'
-```
-
-#### Same label is passed twice to `Sigil`
-
-```ts
-@AttachSigil('Label')
-class A extends Sigil {}
-
-@AttachSigil('Label')
-class B extends Sigil {} // Throws: [Sigil Error] Passed label 'Label' to class 'B' is re-used, passed labels must be unique
-```
-
 #### Invalid label format
 
 ```ts
@@ -314,19 +301,14 @@ updateSigilOptions({ labelValidation: RECOMMENDED_LABEL_REGEX });
 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
-@AttachSigil('@Sigil-auto:label')
-class X extends Sigil {} // Throws: '@Sigil-auto' is a prefix reserved by the library
-```
+class Parent extends Sigil {}
+class Child extends Parent {}
 
-#### Invalid options passed to `updateOptions`
-
-```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
 ```
 
 ---
@@ -352,16 +334,13 @@ updateSigilOptions({ skipLabelUniquenessCheck: 'str' as any }); // Throws: 'upda
 - **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>`
@@ -377,8 +356,8 @@ updateSigilOptions({ skipLabelUniquenessCheck: 'str' as any }); // Throws: 'upda
 - `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
@@ -386,18 +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.
-- `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.
-- `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.
 
 ---
 
@@ -409,9 +388,7 @@ 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
 });
 ```
 
@@ -419,66 +396,28 @@ Values defined in previous example are defaults, per-class overrides available i
 
 ---
 
-## Minimal mode
-
-By default `Sigil` works with minimal mode, You can ignore all decorators and functions and just make base class extend `Sigil`:
-
-```ts
-import { Sigil, updateSigilOptions } from '@vicin/sigil';
-
-// No decorators or functions needed to use 'isOfType' ('instanceof' replacement)
-class A extends Sigil {}
-class B extends A {}
-class C extends B {}
-```
-
-## Strict mode
-
-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:
-
-```ts
-import { updateSigilOptions } from '@vicin/sigil';
-
-updateSigilOptions({ autofillLabels: false });
-```
-
-Now if you forgot to pass a label error is thrown at the moment you create class instance or use any of `Sigil` methods.
-
----
+## Edge cases
 
-## Hot module reload
+### Attach sigil to parent after child
 
-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:
+When attaching `Sigil` labels to classes order from parent -> child must be respected
 
 ```ts
-import { updateSigilOptions } from '@vicin/sigil';
-
-updateSigilOptions({ skipLabelUniquenessCheck: true });
-```
-
-But this can cause unexpected behavior if same label is used for two different classes as checks are disabled globally.
-If you need more strict mode you can pass this options to the re-loaded class only:
+class Parent extends Sigil {}
+class Child extends Parent {}
 
-```ts
-@AttachSigil('HmrClassLabel', { skipLabelUniquenessCheck: true })
-class HmrClass extends Sigil {}
+attachSigil(Child, 'Child');
+attachSigil(Parent, 'Parent'); // Throws: [Sigil Error] Class 'Parent' with label 'Sigil' is already sigilified
 ```
 
-With this approach `skipLabelUniquenessCheck` affects only `HmrClass`, and if `HmrClassLabel` or any other label is re-used error is thrown immediately
-
----
-
-## Edge cases
-
-### Accessing Sigil `metadata` before running 'attachSigil' function
+### Accessing Sigil `metadata` before running `attachSigil` function
 
 If you didn't make sure that `attachSigil` runs right after class declaration and used one of `Sigil` methods this will occur:
 
 ```ts
 class A extends Sigil {}
 
-console.log(A.SigilLabel); // returns auto-generated label (e.g. @Sigil-auto:A:6:a3f15bhl) or throws in strict mode
+console.log(A.SigilLabel); // returns label of the parent (Sigil in our case)
 
 attachSigil(A, 'A');
 
@@ -500,24 +439,21 @@ Note that you can't use `InstanceType` on `private` or `protected` classes, howe
 
 #### Static blocks & IIFE static initializer
 
-Decorators ensure that metadata is appended before static blocks or IIFE static initializers, however `attachSigil` function runs after them so accessing label inside them will return auto-generated label or throw:
+Stage 3 decorators (`AttachSigil`) and function (`attachSigil`) runs after IIFE and static blocks, so accessing `Sigil` metadata inside them should be avoided
 
 ```ts
+@AttachSigil('A')
 class A extends Sigil {
   static IIFE = (() => {
-    const label = A.SigilLabel; // returns auto-generated label (e.g. @Sigil-auto:A:6:a3f15bhl) or throws in strict mode
+    const label = A.SigilLabel; // returns label of the parent (Sigil in our case)
   })();
 
   static {
-    const label = this.SigilLabel; // returns auto-generated label (e.g. @Sigil-auto:A:6:a3f15bhl) or throws in strict mode
+    const label = this.SigilLabel; // returns label of the parent (Sigil in our case)
   }
 }
-
-attachSigil(A, 'A');
 ```
 
-This behavior can't be avoided, so make sure not to call any `Sigil` method inside them or move to decorators (`@AttachSigil`)
-
 ---
 
 ## Benchmarks
@@ -526,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.52 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 ( 71 total tests ) that cover everything from basic mixins to edge cases.
-
 **Coverage Status**
 
 We maintain **100%** test coverage across the entire codebase to ensure that runtime metadata remains consistent and predictable.
@@ -599,22 +562,13 @@ We maintain **100%** test coverage across the entire codebase to ensure that run
 | Funcs  | 100%  |
 | Lines  | 100%  |
 
-**Key Test Areas**
-
-- **Mixins, Attach function & decorator:** Validating `Sigilify`, `AttachSigil` and `attachSigil` 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 even when no attach function or decorator is used.
-- **Lineage:** Verifying that `isOfType` and `isExactType` work across complex inheritance chains.
-- **Error Handling:** Strict validation for all errors and throws.
-- **Edge cases**: Known edge cases.
-
 **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
 ```
 
 ---