@vicin/sigil 2.2.1 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.1.0] - 2026-02-25
+
+### Added
+
+- `isExactType` is added to check for exact instances (children are ingored as well)
+
+### Removed
+
+- `SigilOptions.skipLabelInheritanceCheck` is removed.
+- `isOfTypeStrict` is removed.
+
+## [3.0.0] - 2026-02-24
+
+### Added
+
+- `sigil` symbol used for type-only nominal branding of classes
+
+### Changed
+
+- `__SIGIL_BRAND__` is classes replaced with `sigil` symbol
+
+### Removed
+
+- `withSigilTyped` is removed as library moved into manual branding
+
+### Breaking changes
+
+- `withSigilTyped` is removed as library moved into manual branding
+- `SigilBrandOf` is renamed to `SigilOf`
+- `UpdateSigilBrand` is renamed to `ExtendSigil`
+
 ## [2.2.1] - 2026-02-23
 
 ### Added

package/README.md

@@ -1,8 +1,8 @@
 # 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)
+[![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)
 
-> - 🎉 v2.0.0 is out! Happy coding! 😄💻
+> - 🎉 v3.0.0 is out! Happy coding! 😄💻
 > - 📄 **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
 
 `Sigil` replaces `instanceof` across bundles, enforces nominal class identity, and makes inheritance-aware runtime type checks reliable in large TypeScript systems. It organizes class identities across your codebase and gives you the power of **nominal typing** and **safe cross-bundle class checks** where each class constructor is stored under a unique label.
@@ -15,14 +15,17 @@
 
 ## Important Notes Before Using
 
-- **Explicit class identity:** `Sigil` uses passed class label to identify classes, which means that dev is responsible for uniqueness of classes by passing unique labels.
-- **Performance:** Minimal overhead, but `.isOfType()` is slightly slower than native `instanceof`. Avoid in ultra-hot paths.
-- **Private Constructors:** HOF pattern allows extending private constructors in types (TypeScript limitation).
+- **Explicit class identity:** `Sigil` uses passed class label to identify classes, which means that the developer is responsible for uniqueness of classes by passing unique labels.
 - **Simple instanceof Fix:** If you just need runtime checks without extras, see the [minimal mode](#minimal-mode).
 
-## Why Registry is dropped
+## Features
 
-In v2 we simplified the architecture to remove global registries and reduce complexity across packages.
+- ✅ **Drop-in `instanceof` replacement** that works across bundles, HMR, and monorepos
+- ✅ **True nominal typing** with zero runtime cost
+- ✅ **Inheritance-aware** checks (`isOfType` knows about subclasses)
+- ✅ **Tiny less than 1.5 KB minified and brotlied** measured using size-limit
+- ✅ **Performant as native instanceof** but with guaranteed checks! Also can check for **exact class instance**
+- ✅ Full TypeScript 5.0+ support + excellent JSDoc
 
 ---
 
@@ -33,24 +36,17 @@ In v2 we simplified the architecture to remove global registries and reduce comp
   - [Basic usage](#basic-usage)
   - [Decorator pattern](#decorator-pattern)
   - [HOF pattern](#hof-higher-order-function-pattern)
-  - [Minimal “first-run” example](#minimal-first-run-example)
   - [Migration](#migration)
-- [Limitations & guarantees](#limitations--guarantees)
-  - [What Sigil guarantees](#what-sigil-guarantees)
-  - [What Sigil does not guarantee](#what-sigil-does-not-guarantee)
 - [Core concepts](#core-concepts)
   - [Terminology](#terminology)
   - [Purpose and Origins](#purpose-and-origins)
   - [Implementation Mechanics](#implementation-mechanics)
-- [Nominal typing patterns](#nominal-typing-patterns)
-  - [HOF pattern](#1-hof-pattern-_classclass)
-  - [Decorator pattern](#2-decorator-pattern)
+  - [Inheritance example](#inheritance-example)
 - [API reference](#api-reference)
 - [Options & configuration](#options--configuration)
 - [Minimal mode](#minimal-mode)
 - [Strict mode](#strict-mode)
-- [## Which pattern should I use?](#which-pattern-should-i-use)
-- [Troubleshooting & FAQ](#troubleshooting--faq)
+- [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
 - [License](#license)
 - [Author](#author)
@@ -92,10 +88,8 @@ If your class is marked with `abstract`:
 ```ts
 import { Sigil, SigilifyAbstract } from '@vicin/sigil';
 
-// Using the pre-sigilified base class:
 abstract class User extends Sigil {}
 
-// Or use Sigilify when you want an ad-hoc class:
 const MyClass = SigilifyAbstract(abstract class {}, '@myorg/mypkg.MyClass');
 ```
 
@@ -118,7 +112,7 @@ class User extends Sigil {}
 
 ##### HOF (Higher-Order Function) pattern
 
-Apply a label using HOF as `withSigil` or `withSigilTyped`:
+Apply a label using `withSigil` HOF:
 
 ```ts
 import { Sigil, withSigil } from '@vicin/sigil';
@@ -130,26 +124,6 @@ const user = new User();
 console.log(User.SigilLabel); // "@myorg/mypkg.User"
 ```
 
-> Note: When extending an already sigilified class (for example `Sigil`), you must decorate the subclass or use the HOF helpers in DEV mode unless you configured the library otherwise.
-
-### Minimal “first-run” example
-
-```ts
-import { Sigil, withSigil } from '@vicin/sigil';
-
-class _User extends Sigil {
-  constructor(public name: string) {
-    super();
-  }
-}
-export const User = withSigil(_User, '@myorg/mypkg.User');
-
-const u = new User('alice');
-
-console.log(User.SigilLabel); // "@myorg/mypkg.User"
-console.log(User.isOfType(u)); // true
-```
-
 ### Migration
 
 Migrating old code into `Sigil` can be done with extra couple lines of code only:
@@ -174,33 +148,15 @@ Congratulations — you’ve opted into `Sigil` and you can start replacing `ins
 
 ---
 
-## Limitations & guarantees
-
-This section states clearly what `Sigil` provides and what it does **not** provide.
-
-### What Sigil guarantees
-
-**1. Reliable runtime identity (when used as intended).**
-
-**2. Nominal typing that is inheritance-aware**
-
-### What Sigil does not guarantee
-
-**1. Doesn't work across isolated realms (e.g., iframes, workers) without custom bridging.**
-
-**2. Not for security/access control — constructors can be discoverable.**
-
----
-
 ## Core concepts
 
 ### Terminology
 
-- **Label**: An identity (string) such as `@scope/pkg.ClassName`, but can be random string (e.g. `@Sigil.auto-dq62ib6jnvmmlfbjhxh2937h`) if no label passed.
-- **EffictiveLabel:** A human-readable (string) such as `@scope/pkg.ClassName`, if no label is passed it inherit the last defined label.
+- **Label**: An identity (string) such as `@scope/pkg.ClassName`, but can be random string (e.g. `@Sigil-auto:ClassName:mm2gkdwn:0:g1sq`) if no label passed.
+- **EffectiveLabel:** A human-readable (string) such as `@scope/pkg.ClassName`, if no label is passed it inherit the last defined label.
 - **Label lineage**: Array of labels for ancestry.
 - **Label set**: Set of labels for fast checks.
-- **Brand**: TypeScript marker (`__SIGIL_BRAND__`) for nominal types.
+- **[sigil]**: TypeScript symbol marker for nominal types.
 
 ---
 
@@ -216,143 +172,85 @@ 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
 ```
 
-- **Manual Branding Overhead:** Custom identifiers lead to boilerplate and maintenance issues.
-
-`Sigil` abstracts these into a **centralized system**, making identity management **explicit** and **error-resistant** if defined the right way.
-
-### Implementation Mechanics
-
-- **Runtime Contract:** Established via extending `Sigil` or using `Sigilify` mixin.
-- **Update metadata:** With each new child, HOF or decorators are used to attach metadata and update nominal type.
-- **Accessors & Type guards:** Classes expose `SigilLabel`; instances provide `getSigilLabel()` for querying unique identifier label. also when typed it hold nominal identity used to prevent subtle bugs.
+- **Manual Branding Overhead:** Custom identifiers lead to boilerplate and maintenance issues, `Sigil` add reliable inheritance-aware nominal branding with just one line of code.
 
 ```ts
-import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
-
-// Runtime contract
-class _MyClass extends Sigil {}
+import { sigil } from '@vicin/sigil';
 
-// Update metadata (append new label)
-const MyClass = withSigilTyped(_MyClass, '@scope/package.MyClass');
-type MyClass = GetInstance<typeof MyClass>;
+class User extends Sigil {
+  declare [sigil]: ExtendSigil<'User', Sigil>; // <-- Update nominal brand with this line
+}
 
-// Accessors & Type guards
-console.log(MyClass.SigilLabel); // '@scope/package.MyClass'
-console.log(new MyClass().getSigilLabel()); // '@scope/package.MyClass'
-console.log(MyClass.isOfType(new MyClass())); // true
-function x(c: MyClass) {} // Only instances of 'MyClass' can be passed
+type test1 = User extends Sigil ? true : false; // true
+type test2 = Sigil extends User ? true : false; // false
 ```
 
----
-
-## Nominal typing patterns
-
-In this part we will discuss conventions to avoid any type errors and have nominal typing with just extra few definition lines.
-We have two patterns, **HOF pattern (`_Class`/`Class`)** and **Decorator pattern**:
+`Sigil` abstracts these into a **centralized system**, making identity management **explicit** and **error-resistant** if defined the right way.
 
-### 1. HOF pattern (`_Class`/`Class`)
+### Implementation Mechanics
 
-Define implementation in an untyped class, then wrap for typing:
+- **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.
 
 ```ts
-import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
+import { Sigil, WithSigil, sigil, ExtendSigil } from '@vicin/sigil';
 
-class _X extends Sigil {
-  // Class logic here
+@WithSigil('@scope/package.MyClass') // <-- Run-time values update
+class MyClass extends Sigil {
+  declare [sigil]: ExtendSigil<'@scope/package.MyClass', Sigil>; // <-- compile-time type update
 }
-export const X = withSigilTyped(_X, 'Label.X');
-export type X = GetInstance<typeof X>;
 ```
 
-#### `InstanceType<>` vs `GetInstance<>`
-
-You should depend on `GetInstance` to get type of instance and avoid using `InstanceType` as it returns `any` if the class constructor is `protected` or `private`.
-
-```ts
-export type X = GetInstance<typeof X>; // <-- works with 'private' and 'protected' constructors as well
-```
-
-Internally `GetInstance` is just `T extends { prototype: infer R }`.
-
-#### Generic propagation
+You can avoid decorators and use HOF but they are slightly more verbose:
 
 ```ts
-class _X<G> extends Sigil {}
-export const X = withSigilTyped(_X, 'Label.X');
-export type X<G> = GetInstance<typeof X<G>>; // <-- Redeclare generics here
-
-class _Y<G> extends X<G> {} // and so on...
-```
-
-#### Anonymous classes
-
-You may see error: `Property 'x' of exported anonymous class type may not be private or protected.`, although this is rare to occur.
-This comes from the fact that all typed classes are `anonymous class` as they are return of HOF. to avoid these error entirely all you need is exporting the untyped classes even if they are un-used as a good convention.
+import { Sigil, withSigil, sigil, ExtendSigil } from '@vicin/sigil';
 
-```ts
-export class _X extends Sigil {} // <-- Just add 'export' here
-export const X = withSigilTyped(_X, 'Label.X');
-export type X = GetInstance<typeof X>;
-```
-
-#### Private constructors
-
-The only limitation in HOF approach is **extending private constructors**:
-
-```ts
-import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
-class _X extends Sigil {
-  private constructor() {}
+class _MyClass extends Sigil {
+  declare [sigil]: ExtendSigil<'@scope/package.MyClass', Sigil>;
 }
-const X = withSigilTyped(_X, 'X');
-type X = GetInstance<typeof X>;
-
-class _Y extends X {} // <-- This is allowed!
-const Y = withSigilTyped(_Y, 'Y');
-type Y = GetInstance<typeof Y>;
 
-const y = new Y(); // <-- Type here is any
+const MyClass = withSigil(_MyClass, '@scope/package.MyClass');
+type MyClass = InstanceType<typeof MyClass>;
 ```
 
-This is a known TypeScript limitation.
-
----
+Note that you can't use `InstanceType` on `private` or `protected` classes.
 
-### 2. Decorator pattern
-
-Inject brand directly in class body:
+### Inheritance example
 
 ```ts
-import { Sigil, WithSigil, UpdateSigilBrand } from '@vicin/sigil';
+import { Sigil, WithSigil } from '@vicin/sigil';
 
-@WithSigil('X')
-class X extends Sigil {
-  declare __SIGIL_BRAND__: UpdateSigilBrand<'X', Sigil>;
+@WithSigil('@myorg/User')
+class User extends Sigil {
+  declare [sigil]: ExtendSigil<'@myorg/User', Sigil>;
 }
 
-@WithSigil('Y')
-class Y extends X {
-  declare __SIGIL_BRAND__: UpdateSigilBrand<'Y', X>;
+@WithSigil('@myorg/Admin')
+class Admin extends User {
+  declare [sigil]: ExtendSigil<'@myorg/Admin', User>;
 }
-```
-
-No `_Class`/`Class` pattern, no `private constructor` issue, no type hacks and only one extra line, but our branding logic now lives in class body.
-
-#### Label Consistency
 
-Use typeof label for compile-time matching:
+const admin = new Admin();
+const user = new User();
 
-```ts
-import { Sigil, WithSigil, UpdateSigilBrand } from '@vicin/sigil';
+// 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
 
-const label = 'X';
+// Exact checks
+console.log(Admin.isOfType(admin)); // true
+console.log(Admin.isOfType(user)); // false
+console.log(User.isOfType(user)); // true
+console.log(User.isOfType(admin)); // false (Admin is child indeed but this checks for user specifically)
 
-@WithSigil(label)
-class X extends Sigil {
-  declare __SIGIL_BRAND__: UpdateSigilBrand<typeof label, Sigil>;
-}
+type test1 = Admin extends User ? true : false; // true
+type test2 = User extends Admin ? true : false; // false
 ```
 
 ---
@@ -374,7 +272,6 @@ class X extends Sigil {
 
 - **HOFs:**
   - `withSigil(Class, label?, opts?)`
-  - `withSigilTyped(Class, label?, opts?)`
 
 - **Helpers:**
   - `isSigilCtor(ctor)`
@@ -392,20 +289,17 @@ class X extends Sigil {
   - `ISigil<Label, ParentSigil?>`
   - `ISigilStatic<Label, ParentSigil?>`
   - `ISigilInstance<Label, ParentSigil?>`
-  - `SigilBrandOf<T>`
-  - `TypedSigil<SigilClass, Label>`
-  - `GetInstance<T>`
-  - `UpdateSigilBrand<Label, Base>`
+  - `SigilOf<T>`
+  - `ExtendSigil<Label, Parent>`
   - `SigilOptions`
 
 ### Key helpers (runtime)
 
 - `Sigil`: a minimal sigilified base class you can extend from.
 - `SigilError`: an `Error` class decorated with a `Sigil` so it can be identified at runtime.
-- `WithSigil(label)`: class decorator that attaches `Sigil` metadata at declaration time.
 - `Sigilify(Base, label?, opts?)`: mixin function that returns a new constructor with `Sigil` types and instance helpers.
+- `WithSigil(label)`: class decorator that attaches `Sigil` metadata at declaration time.
 - `withSigil(Class, label?, opts?)`: HOF that validates and decorates an existing class constructor.
-- `withSigilTyped(Class, label?, opts?)`: like `withSigil` but narrows the TypeScript type to include brands.
 - `isSigilCtor(value)`: `true` if `value` is a `Sigil` constructor.
 - `isSigilInstance(value)`: `true` if `value` is an instance of a `Sigil` constructor.
 - `updateSigilOptions(opts)`: change global runtime options before `Sigil` decoration (e.g., `autofillLabels`).
@@ -417,11 +311,11 @@ When a constructor is decorated/sigilified it will expose the following **static
 
 - `SigilLabel` — the identity label string.
 - `SigilEffectiveLabel` — the human label string.
-- `SigilLabelLineage` — readonly array of labels representing parent → child.
-- `SigilLabelSet` — readonly `Set<string>` for O(1) checks.
+- `SigilLabelLineage` — readonly array of labels representing parent → child for debugging.
+- `SigilLabelSet` — readonly `Set<string>` for debugging.
 - `isSigilified(obj)` — runtime predicate that delegates to `isSigilInstance`.
-- `isOfType(other)` — O(1) membership test using `other`'s `__LABEL_SET__`.
-- `isOfTypeStrict(other)` — strict lineage comparison element-by-element.
+- `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.
 
 Instances of sigilified classes expose instance helpers:
 
@@ -429,8 +323,8 @@ Instances of sigilified classes expose instance helpers:
 - `getSigilEffectiveLabel()` — returns the human label.
 - `getSigilLabelLineage()` — returns lineage array.
 - `getSigilLabelSet()` — returns readonly Set.
-- `isOfType(other)` — O(1) membership test using `other`'s `__LABEL_SET__`.
-- `isOfTypeStrict(other)` — strict lineage comparison element-by-element.
+- `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.
 
 ---
 
@@ -467,7 +361,7 @@ class C extends B {}
 
 ## Strict mode
 
-If you want to inforce passing a label to every class defined in your codebase, you can set `autofillLabels` to `false` at the start of app:
+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';
@@ -479,20 +373,49 @@ Now if you forgot to pass a label error is thrown.
 
 ---
 
-## Which pattern should I use?
+## Benchmarks
 
-- Want simplest setup? → Extend `Sigil`
-- Want full nominal typing? → Use HOF pattern
-- Want clean class bodies? → Use HOF
-- Want fewer wrapper exports? → Use Decorators
+Sigil is built for **real-world performance**. Below are the latest micro-benchmark results (run on **Node.js v20.12.0**).
+To run benchmarks on your machine fetch source code from [github](https://github.com/ZiadTaha62/sigil) and run `npm run bench` in your console.
 
----
+### 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` has **practically the same performance as native `instanceof`**, slightly **slower** on static calls and slightly **faster** on the instance side.
+> `isExactType` adds only a tiny negligible cost and remains extremely fast even on deep hierarchies.
+
+### 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                   |
+
+> **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.
+
+### Bundle Size
 
-## Troubleshooting & FAQ
+**less than 1.5 KB** (minified + Brotli, including all dependencies)
 
-- **Dev Extension Errors:** Add labels or enable autofillLabels.
-- **Anonymous Class Errors:** Export untyped bases.
-- **Selective Labeling:** Use `autofillLabels: true` or empty `@WithSigil()` for auto-generation.
+This makes Sigil one of the smallest full-featured solutions for nominal typing + reliable runtime identity.
 
 ---