@vicin/phantom 1.0.1

package/README.md

@@ -0,0 +1,869 @@
+# Phantom
+
+`Phantom` is a powerful, lightweight TypeScript library for nominal typing. it uses **type-only** metadata object that can be attached to any type with clean IDE. It enables compile-time distinctions between structurally identical types (e.g., `Email` vs. `Username` as branded strings) while supporting advanced features like **constrained identities**,**state variants**, **additive traits**, and **reversible transformations**. making it ideal for domain-driven design (DDD), APIs, and type-safe primitives with minimal performance overhead.
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Install](#install)
+- [Core concepts](#core-concepts)
+- [Phantom](#phantom-1)
+- [Chaining](#chaining)
+- [Hot-path code ( truly type-only pattern )](#hot-path-code--truly-type-only-pattern-)
+- [Debugging](#debugging)
+- [API reference](#api-reference)
+- [Full examples](#full-examples)
+- [Sigil](#sigil)
+- [Contributing](#contributing)
+- [License](#license)
+- [Author](#author)
+
+## Features
+
+- **Nominal branding for primitives and objects to prevent accidental misuse (e.g., UserId ≠ PostId).**
+
+- **Constrained identities with base types and variants for enforced type safety.**
+
+- **Traits as independent, additive metadata sets for capabilities or flags.**
+
+- **Transformations for reversible type changes (e.g., encrypt/decrypt) while tracking origins.**
+
+- **assertors as zero-cost runtime helpers for applying metadata via type casts.**
+
+- **Modular namespaces: So all devs are happy.**
+
+---
+
+## Install
+
+```Bash
+npm install @vicin/phantom
+# or
+yarn add @vicin/phantom
+# or
+pnpm add @vicin/phantom
+```
+
+**Requirements:** TypeScript 5.0+ recommended.
+
+---
+
+## Core concepts
+
+### Terminology
+
+- **Label:** Optional human-readable description (e.g., "User ID")—does not affect typing.
+
+- **Tag:** Unique nominal identifier (string/symbol) for brands/identities/transformations.
+
+- **Variants:** Mutually exclusive states (e.g., "Verified" | "Unverified") for identities/transformations.
+
+- **Base:** Runtime type constraint (e.g., string) enforced on assignment.
+
+- **Input:** Original type preserved in transformations for reversion.
+
+- **Traits:** Key-value map of capabilities (e.g., { PII: true }) that can be added/removed independently.
+
+- **Brand:** Basic nominal tag with optional label.
+
+- **Identity:** Brand + base/variants for constrained nominals.
+
+- **Trait:** Additive metadata flag.
+
+- **Transformation:** Reversible change with input tracking.
+
+---
+
+### \_\_Phantom object
+
+Under the hood `Phantom` is just **type-only** metadata object appended to your types and gets updated every time one of phantom types is used. This allows mimicking nominal typing inside TypeScript's structural typing.
+
+When `Phantom` is used with it's full potential the IDE will show you something like this:
+
+```ts
+type X = string & {
+  __Phantom: {
+    __Tag: 'X';
+    __Label?: 'Label of X';
+    __Variants: 'Variant1' | 'Variant2';
+    __Traits: {
+      trait1: true;
+      trait2: true;
+    };
+    __Input: SomeInput;
+    __OriginalType?: string;
+  };
+};
+```
+
+From the first glance you can spot that`Phantom` is designed to separate original type `string` from `__Phantom` metadata object so your IDE can stay clean, each Phantom object will have these fields:
+
+- **\_\_Tag:** Nominal tag (**identity**) of the type which tells who this value is. can be `string` | `symbol`.
+
+- **\_\_Label?:** Optional label describing this nominal identity.
+
+- **\_\_Variants:** Optional states of the nominal identity.
+
+- **\_\_Traits:** Additional properties the type holds, unlike `__Tag` that tells who `__Traits` tell what this type hold or can do (e.g. `Validated`, `PII` etc...).
+
+- **\_\_Input:** Input type in transformations (e.g. Transformation `Encrypted` can have `__Input: string` which means that encrypted value is `string`).
+
+- **\_\_OriginalType?:** Type without `__Phantom` metadata object. related to internal implementation only and is crucial to keep clean IDE messages.
+
+More details of these properties will be discussed later.
+
+---
+
+## Phantom
+
+### Branding
+
+Use brands for simple nominal distinctions on primitives.
+
+#### Structure
+
+**`Brand.Declare<Tag, Label?>`**
+
+- **Tag:** Unique identifier which can string or symbol.
+- **Label?:** Optional label description. can be set to `never`.
+
+#### Basic example
+
+```ts
+import { Phantom } from '@vicin/phantom';
+
+// Declare a brand
+type UserId = Phantom.Brand.Declare<'UserId', 'Unique user identifier'>;
+
+// Assertor for assigning the brand
+const asUserId = Phantom.assertors.asBrand<UserId>();
+
+// Usage
+const id: string = '123';
+const userId = asUserId(id); // type: string & { __Phantom: { __Tag: "UserId"; __Label?: "Unique user identifier"; __OriginalType: string; } }
+
+// Type safety: prevents assignment
+let postId: string = 'abc';
+postId = userId; // Type error: 'UserId' is not assignable to unbranded string
+```
+
+#### Re-brand
+
+Branding already branded value is prohibited and results in Error type:
+
+```ts
+const value = '123';
+
+// Branding string as UserId
+const userId = asUserId(value);
+
+// Trying to brand userId as PostId returns type error
+const postId = asPostId(userId); // type: Flow.TypeError<{ code: "ALREADY_BRANDED"; message: "Type already branded"; context: { type: <userId type>; }; }>
+```
+
+---
+
+### Identities with constraints
+
+`Identity` is just `Brand` with extra capabilities as `Base` and `Variants` for more complex use cases.
+
+#### Structure
+
+**`Identity.Declare<Tag, Label?, Base?, Variants?>`**
+
+- **Tag:** Unique identifier which can string or symbol.
+- **Label?:** Optional label description. can be set to `never`.
+- **Base?:** Optional base that constrains identity so only `string` for example can be casted as `Email`. can be set to `never`.
+- **Variants?:** Optional variants (states) of the identity. can be set to `never`.
+
+#### Basic example
+
+```ts
+import { Phantom } from '@vicin/phantom';
+
+// Declare an identity with base (string) and variants
+type Email = Phantom.Identity.Declare<
+  'Email',
+  'User email address',
+  string,
+  'Verified' | 'Unverified'
+>;
+
+// Assertor
+const asEmail = Phantom.assertors.asIdentity<Email>();
+
+// Usage
+const email = asEmail('user@example.com'); // type: string & { __Phantom: { __Tag: "Email"; __Label?: "User email address"; __Variants: "Verified" | "Unverified"; __OriginalType: string; } }
+```
+
+#### Re-brand
+
+Branding already branded value is prohibited and results in Error type:
+
+```ts
+const value = '123';
+
+// Branding string as UserId
+const userId = asUserId(value);
+
+// Trying to brand userId as PostId returns type error
+const postId = asPostId(userId); // type: Flow.TypeError<{ code: "ALREADY_BRANDED"; message: "Type already branded"; context: { type: <userId type>; }; }>
+```
+
+#### Base
+
+```ts
+const validBase = asEmail('user@example.com');
+
+const inValidBase = asEmail(123); // type:  Flow.TypeError<{ code: "TYPE_NOT_EXTEND_BASE"; message: "Type not extend base"; context: { type: 123; base: string; }; }>
+```
+
+#### Variants
+
+```ts
+// With variant
+type VerifiedEmail = Phantom.Identity.WithVariant<Email, 'Verified'>;
+const asVerifiedEmail = Phantom.assertors.asIdentity<VerifiedEmail>();
+
+// Usage
+const verifiedEmail = asVerifiedEmail('user@verified.com'); // type: string & { __Phantom: { __Tag: "Email"; __Label?: "User email address"; __Variants: "Verified"; __OriginalType: string; } }
+
+// Behavior
+type test1 = VerifiedEmail extends Email ? true : false; // true as all VerifiedEmails are Emails
+type test2 = Email extends VerifiedEmail ? true : false; // false as not all Emails are VerifiedEmails
+```
+
+---
+
+### Traits (additive capabilities)
+
+Traits allow independent metadata addition/removal.
+
+#### Structure
+
+**`Trait.Declare<Trait>`**
+
+- **Trait:** Unique identifier which can string or symbol.
+
+#### Basic example
+
+```ts
+import { Phantom } from '@vicin/phantom';
+
+// types
+type PII = Phantom.Trait.Declare<'PII'>;
+
+// assertors
+const addPII = Phantom.assertors.addTrait<PII>();
+const dropPII = Phantom.assertors.dropTrait<PII>();
+
+// add trait
+let location = 'location';
+location = addPII(location); // type: string & { __Phantom: { __Traits: { PII: true; }; __OriginalType: string; } }
+
+// drop trait
+location = dropPII(location); // type: string
+```
+
+#### Multi add and drop
+
+```ts
+// types
+type PII = Phantom.Trait.Declare<'PII'>;
+type Validated = Phantom.Trait.Declare<'Validated'>;
+
+// assertors
+const addValidatedPII = Phantom.assertors.addTraits<[PII, Validated]>();
+const dropValidatedPII = Phantom.assertors.dropTraits<[PII, Validated]>();
+
+// add traits
+let location = 'location';
+location = addValidatedPII(location); // type: string & { __Phantom: { __Traits: { PII: true; Validated: true; }; __OriginalType: string; } }
+
+// drop traits
+location = dropValidatedPII(location); // type: string
+```
+
+---
+
+### Transformations (Type pipe-like behavior)
+
+Traits allow complex type transformations that remember original value, it defines new identity of the value (e.g. `Encoded`) while storing original input type (e.g. `string`).
+
+So basically you have:
+
+- **Transformed:** New type after transformation (e.g. `Uint8Array` after `Encoding`).
+- **Input:** Original type of value (e.g. `string`, `number` or whatever value that is `Encoded`).
+
+Type identity is `Transformed` and stores `Input` under special field inside `__Phantom` which is `__Input`.
+
+#### Structure
+
+**`Transformation.Declare<Input, Tag, Label?, Base?, Variants?>`**
+
+- **Input:** Type input to the transformation.
+- **Tag:** Unique identifier of transformed which can string or symbol.
+- **Label?:** Optional label description of transformed. can be set to `never`.
+- **Base?:** Optional base that constrains identity of transformed so only `Uint8Array` for example can be casted as `Encoded`. can be set to `never`.
+- **Variants?:** Optional variants (states) of the identity. can be set to `never`.
+
+#### Basic example
+
+```ts
+import { Phantom } from '@vicin/phantom';
+
+// type
+type Encoded<I = unknown> = Phantom.Transformation.Declare<
+  I,
+  'Encoded',
+  'Encoded value',
+  Uint8Array // Encoded value should be 'Uint8Array'
+>;
+
+// assertors
+const applyEncode = Phantom.assertors.applyTransformation<Encoded>();
+const revertEncode = Phantom.assertors.revertTransformation<Encoded>();
+```
+
+As you have seen the type `Encoded` is generic, so we can pass `Input` to it and represent any type we want to mark as being `Encoded`.
+
+#### Apply / Revert pattern
+
+Now we define our `Encode` function to apply and revert transformation:
+
+```ts
+function encode<V>(value: V) {
+  const encoded = value as Uint8Array; // replace with actual encoding
+  return applyEncode(value, encoded);
+}
+
+function decode<E extends Encoded>(encoded: E) {
+  const decoded = encoded; // replace with actual decoding
+  return revertEncode(encoded, decoded);
+}
+
+const value = 'some value';
+const encoded = encode(value); // type: Uint8Array<ArrayBufferLike> & { __Phantom: { __Input: string; __Tag: "Encoded"; __Label?: "Encoded value"; __OriginalType?: Uint8Array<ArrayBufferLike>; }; }
+const decoded = decode(encoded); // type: string
+```
+
+#### Repeated Apply / Revert
+
+You can apply single transformation multiple times on a value and `Phantom` will store value from each step as an `Input` to the next step, so if you encoded single value 2 times you will need to decode it 2 times as well to get the original type.
+
+```ts
+const value = 'some value';
+const encoded1 = encode(value); // '__Input' here is 'string'
+const encoded2 = encode(encoded1); // '__Input' here is 'typeof encoded1'
+const decoded1 = decode(encoded2); // type here is 'typeof encoded2'
+const original = decode(decoded1); // type here is 'string'
+```
+
+Same applies to different transformations, so if you `Encoded` then `Encrypted` a value, you will need to `Decrypt` first then `Decode`.
+
+#### Base
+
+Same behavior as [`Identity`](#identities-with-constraints)
+
+#### Variants
+
+Same behavior as [`Identity`](#identities-with-constraints)
+
+---
+
+### Errors
+
+This library return `ErrorType` instead of using type constraints or returning `never` which makes debugging for errors much easier.
+When passed value violate specific rule, descripted `ErrorType` is returned.
+
+**ErrorTypes:**
+
+- **ALREADY_BRANDED:** Error returned if already branded value (with either `Brand` or `Identity`) is passed to `.Assign<>` again.
+
+- **TYPE_NOT_EXTEND_BASE:** Error returned if type not extend `Base` constraint of `Identity`.
+
+- **TRANSFORMATION_MISMATCH:** Error returned if type passed to `Transformation.Revert<>` is different from `Transformation` intended.
+
+- **NOT_TRANSFORMED:** Error returned if you tried to revert a non-transformed type.
+
+All the types inside `Phantom` check for `ErrorType` first before applying any change, so if you tried to pass `ErrorType` to `Brand.Assign<>` or `asBrand<B>()` for example the error will return unchanged.
+
+---
+
+### Symbols
+
+In earlier examples we used strings as our tags just for simplicity, this is acceptable but in real-life projects it's better to use `unique symbol` as a tag so your types are truly unique.
+
+```ts
+import { Phantom } from '@vicin/phantom';
+
+// type
+declare const __UserId: unique symbol;
+type UserId = Phantom.Brand.Declare<typeof __UserId, 'User id'>;
+
+// assertor
+export const asUserId = Phantom.assertors.asBrand<UserId>();
+```
+
+Now `UserId` can't be re-defined anywhere else in the codebase.
+
+---
+
+### Imports
+
+Some devs (including me) may find `Phantom` namespace everywhere repetitive and prefer using `Brand` or `assertors` directly, every namespace under `Phantom` can be imported alone:
+
+```ts
+import { Brand, assertors } from '@vicin/phantom';
+
+// type
+declare const __UserId: unique symbol; // declare type only unique symbol to be our tag
+type UserId = Brand.Declare<typeof __UserId, 'User id'>;
+
+// assertor
+export const asUserId = assertors.asBrand<UserId>();
+```
+
+Also if you prefer default imports you can just:
+
+```ts
+import P from '@vicin/phantom';
+
+// type
+declare const __UserId: unique symbol; // declare type only unique symbol to be our tag
+type UserId = P.Brand.Declare<typeof __UserId, 'User id'>;
+
+// assertor
+export const asUserId = P.assertors.asBrand<UserId>();
+```
+
+You are free to pick whatever pattern you are comfortable with.
+
+---
+
+## Chaining
+
+If you need to call multiple assertors on a single value (e.g. mark brand and attach two traits) the code can get messy:
+
+```ts
+import { Brand, Trait, assertors } from '@vicin/phantom';
+
+type UserId = Brand.Declare<'UserId'>;
+const asUserId = assertors.asBrand<UserId>();
+
+type PII = Trait.Declare<'PII'>;
+const addPII = assertors.addTrait<PII>();
+
+type Validated = Trait.Declare<'Validated'>;
+const addValidated = assertors.addTrait<Validated>();
+
+const userId = addValidated(addPII(asUserId('123'))); // <-- ugly nesting
+```
+
+Instead you can use `PhantomChain` class:
+
+```ts
+import { PhantomChain } from '@vicin/phantom';
+
+const userId = new PhantomChain('123')
+  .with(asUserId)
+  .with(addPII)
+  .with(addValidated)
+  .end();
+```
+
+The `.with()` is order sensitive, so previous example is equivalent to `addValidated(addPII(asUserId("123")))`. also if any `ErrorType` is retuned at any stage of the chain, the chain will break and error will propagate unchanged making debugging much easier.
+
+**Note:**
+
+- With every step new `PhantomChain` instance is created, in most apps this is negligible as `PhantomChain` is just simple object with two methods but avoid using it in hot paths.
+
+---
+
+## Hot-path code ( truly type-only pattern )
+
+In hot-path code every function call matters, and although assertor functions makes code much cleaner but you may prefer to use `as` in performance critical situations so `Phantom` lives in type system entirely and have zero run-time trace, these examples defines best practices to do so:
+
+**Brand**:
+
+```ts
+import { Brand } from '@vicin/phantom';
+
+type UserId = Brand.Declare<'UserId'>;
+type AsUserId<T> = Brand.Assign<UserId, T>;
+
+const userId = '123' as AsUserId<string>;
+```
+
+**Identity**:
+
+```ts
+import { Identity } from '@vicin/phantom';
+
+type PostId = Identity.Declare<'PostId'>;
+type AsPostId<T> = Identity.Assign<UserId, T>;
+
+const postId = '123' as AsPostId<string>;
+```
+
+**Trait**:
+
+```ts
+import { Trait } from '@vicin/phantom';
+
+type PII = Trait.Declare<'PII'>;
+type AddPII<T> = Trait.Add<PII, T>;
+type DropPII<T> = Trait.Drop<PII, T>;
+
+let location1 = 'location' as AddPII<string>;
+let location2 = location1 as DropPII<typeof location1>;
+```
+
+**Transformation**:
+
+```ts
+import { Transformation } from '@vicin/phantom';
+
+type Encoded<T> = Transformation.Declare<T, 'Encoded'>;
+type ApplyEncoded<I, T> = Transformation.Apply<Encoded<any>, I, T>;
+type RevertEncoded<T, I> = Transformation.Revert<Encoded<any>, T, I>;
+
+function encode<V>(value: V) {
+  const encoded = value as Uint8Array; // replace with actual encoding
+  return encoded as ApplyEncoded<V, typeof encoded>;
+}
+
+function decode<E extends Encoded>(encoded: E) {
+  const decoded = encoded as string; // replace with actual decoding
+  return decoded as RevertEncoded<E, typeof decoded>;
+}
+```
+
+**Chaining**:
+
+Chaining is not supported in **type-only pattern** and nesting is the only way to reliably calculate types:
+
+```ts
+import { Brand, Trait, assertors } from '@vicin/phantom';
+
+type UserId = Brand.Declare<'UserId'>;
+type AsUserId<T> = Brand.Assign<UserId, T>;
+
+type PII = Trait.Declare<'PII'>;
+type AddPII<T> = Trait.Add<PII, T>;
+
+type Validated = Trait.Declare<'Validated'>;
+type AddValidated<T> = Trait.Add<Validated, T>;
+
+const userId = '123' as AddValidated<AddPII<AsUserId<string>>>;
+```
+
+**Note:**
+
+- Maintainability of code is crucial, Use **type-only pattern** only when you have to, but in most cases it's adviced to use assertor functions.
+
+---
+
+## Debugging
+
+When debugging the `__Phantom` object can complicate IDE messages, you can temporarly add `StripPhantom` type or `stripPhantom` function.
+
+---
+
+## API reference
+
+### Core Metadata Namespaces
+
+These handle individual metadata fields in the `__Phantom` object.
+
+- **Label:** Descriptive strings (optional).
+  - `Any`: Marker for labeled types.
+  - `LabelOf<T>`: Extract label from `T`.
+  - `HasLabel<T, L>`: Check if `T` has label `L`.
+
+- **Tag:** Unique nominal identifiers (string/symbol).
+  - `Any`: Marker for tagged types.
+  - `TagOf<T>`: Extract tag from `T`.
+  - `HasTag<T, Ta>`: Check if `T` has tag `Ta`.
+
+- **Variants:** Mutually exclusive states (string unions).
+  - `Any`: Marker for variant-bearing types.
+  - `VariantsOf<T>`: Extract variant union from `T`.
+  - `HasVariants<T>`: Check if `T` has variants.
+
+- **Base:** Runtime type constraints.
+  - `Any`: Marker for base-constrained types.
+  - `BaseOf<T>`: Extract base from `T`.
+  - `HasBase<T, B>`: Check if `T` has base `B`.
+
+- **Input:** Original types in transformations.
+  - `Any`: Marker for input-bearing types.
+  - `InputOf<T>`: Extract input from `T`.
+  - `HasInput<T, I>`: Check if `T` has input `I`.
+
+- **Traits:** Additive capability maps (e.g., `{ TraitKey: true }`).
+  - `Any`: Marker for trait-bearing types.
+  - `TraitsOf<T>`: Extract trait map from `T`.
+  - `TraitKeysOf<T>`: Extract trait keys from `T`.
+  - `HasTraits<T, Tr>`: Check if `T` has trait `Tr`.
+
+### Feature Namespaces
+
+These provide nominal typing and metadata operations.
+
+- **Brand:** Simple nominal branding.
+  - `Any`: Marker for branded types.
+  - `Declare<T, L>`: Declare a brand with tag `T` and optional label `L`.
+  - `Assign<B, T>`: Assign brand `B` to `T` (fails if already branded).
+  - `AssignSafe<B, T>`: Assign if possible, else return `T`.
+  - `isBrand<T, B>`: Check if `T` is branded with `B`.
+
+- **Identity**: Brands with bases and variants.
+  - `Any`: Marker for identity types.
+  - `Declare<T, L, B, V>`: Declare identity with tag `T`, label `L`, base `B`, variants `V`.
+  - `Assign<I, T>`: Assign identity `I` to `T` (fails if already branded).
+  - `AssignSafe<I, T>`: Safe assignment, return `T` is already has identity.
+  - `WithVariant<I, V>`: Set variant `V` on identity `I`.
+  - `WithTypeVariant<T, V>`: Set variant `V` on type `T`.
+  - `isIdentity<T, I>`: Check if `T` matches identity `I`.
+
+- **Trait:** Additive/removable capabilities.
+  - `Any`: Marker for trait types.
+  - `Declare<Tr>`: Declare trait with key `Tr`.
+  - `Add<Tr, T>`: Add trait `Tr` to `T`.
+  - `AddMulti<Tr[], T>`: Add multiple traits to `T`.
+  - `Drop<Tr, T>`: Remove trait `Tr` from `T`.
+  - `DropMulti<Tr[], T>`: Remove multiple traits from `T`.
+  - `HasTrait<T, Tr>`: Check if `T` has trait `Tr`.
+
+- **Transformation:** Reversible type changes with input tracking.
+  - `Any`: Marker for transformation types.
+  - `Declare<I, T, L, B, V>`: Declare transformation with input `I`, tag `T`, label `L`, base `B`, variants `V`.
+  - `Apply<Tr, I, T>`: Apply transformation `Tr` from input `I` to `T`.
+  - `Revert<Tr, T, I>`: Revert transformation `Tr` from `T` to input `I`.
+  - `RevertAny<T, I>`: Revert any transformation from `T` to `I`.
+  - `isTransformed<T, Tr>`: Check if `T` is transformed with `Tr`.
+
+### Inspect Namespace
+
+Query utilities for metadata.
+
+- `PhantomOf<T>`: Extract full `__Phantom` object from `T`.
+- `StripPhantom<T>`: Remove `__Phantom` from `T`.
+- `stripPhantom(value)`: Runtime helper to strip metadata (for debugging).
+
+Aliases for core and feature extractors: `LabelOf<T>`, `HasLabel<T, L>`, `TagOf<T>`, `HasTag<T, Ta>`, `VariantsOf<T>`, `HasVariants<T>`, `BaseOf<T>`, `HasBase<T, B>`, `InputOf<T>`, `HasInput<T>`, `TraitsOf<T>`, `TraitKeysOf<T>`, `HasTraits<T, Tr>`, `isBrand<T, B>`, `isIdentity<T, I>`, `HasTrait<T, Tr>`, `isTransformed<T, Tr>`.
+
+### assertors Namespace
+
+Zero-cost casting functions.
+
+`asBrand<B>()`: Assign brand `B`.
+`asIdentity<I>()`: Assign identity `I`.
+`addTrait<Tr>()`: Add trait `Tr`.
+`addTraits<Tr[]>()`: Add multiple traits `Tr[]`.
+`dropTrait<Tr>()`: Remove trait `Tr`.
+`dropTraits<Tr[]>()`: Remove multiple traits `Tr[]`.
+`applyTransformation<Tr>()`: Apply transformation `Tr` (takes `input`, `transformed`).
+`revertTransformation<Tr>()`: Revert transformation `Tr` (takes `transformed`, `input`).
+
+### Other Utilities
+
+`ErrorType<E>`: Unique error type for violations (e.g., `already branded`).
+`PhantomChain`: Fluent class for chaining assertors (`.with(assertor)` and `.end()`).
+
+---
+
+## Full examples
+
+### Brand & Identity
+
+Defining brands and identities at our app entry points after validation:
+
+```ts
+import { Brand, assertors } from '@vicin/phantom';
+
+declare const __UserId: unique symbol;
+type UserId = Brand.Declare<typeof __UserId, 'UserId'>;
+const asUserId = assertors.asBrand<UserId>();
+
+function validateUserId(userId: string) {
+  const valid = userId; // replace with actual validation
+  return asUserId(valid);
+}
+
+// Function guarded by UserId so only return of asUserId in our validation function can be passed here
+function registerUser(userId: UserId) {
+  // handle registring
+}
+
+const input = 'some user id';
+const validUserId = validateUserId(input);
+registerUser(validUserId); // no error
+registerUser('Invalid user id'); // throws an error: Argument of type 'string' is not assignable to parameter of type '{ __Phantom: { __Tag: unique symbol; __Label?: "UserId"; }; }'.
+```
+
+---
+
+### Traits
+
+Marking values with special traits, for example 'PII' to avoid logging personal information:
+
+```ts
+import { Trait, assertors } from '@vicin/phantom';
+
+declare const __PII: unique symbol;
+type PII = Phantom.Trait.Declare<typeof __PII>;
+const addPII = Phantom.assertors.addTrait<PII>();
+
+function log<T>(value: T extends PII ? never : T) {}
+
+const publicValue = 'some value';
+const secretValue = addPII('secret value');
+
+log(publicValue); // no error
+log(secretValue); // throws an error: Argument of type '_Add<PII, "secret value">' is not assignable to parameter of type 'never'.
+```
+
+---
+
+### Transformation
+
+Transformations shine in pipelines, typically `apply`/`revert` assertors are used inside `apply`/`revert` functions, which creates full type-safe pipe that remember type before each step:
+
+```ts
+import { Transformation, assertors } from '@vicin/phantom';
+
+/** --------------------------
+ * Encode type and functions
+ * -------------------------- */
+
+declare const __Encoded: unique symbol;
+type Encoded<I = unknown> = Transformation.Declare<
+  I,
+  typeof __Encoded,
+  'Encoded value',
+  Uint8Array
+>;
+const applyEncode = assertors.applyTransformation<Encoded>();
+const revertEncode = assertors.revertTransformation<Encoded>();
+
+function encode<V>(value: V) {
+  const encoded = value as Uint8Array; // replace with actual encoding
+  return applyEncode(value, encoded);
+}
+
+function decode<E extends Encoded>(encoded: E) {
+  const decoded = encoded; // replace with actual decoding
+  return revertEncode(encoded, decoded);
+}
+
+/** --------------------------
+ * Encrypt type and functions
+ * -------------------------- */
+
+declare const __Encrypted: unique symbol;
+type Encrypted<I = unknown> = Transformation.Declare<
+  I,
+  typeof __Encrypted,
+  'Encrypted value',
+  Uint8Array
+>;
+const applyEncrypt = assertors.applyTransformation<Encrypted>();
+const revertEncrypt = assertors.revertTransformation<Encrypted>();
+
+function encrypt<V>(value: V) {
+  const encrypted = value as Uint8Array; // replace with actual encryption
+  return applyEncrypt(value, encrypted);
+}
+
+function decrypt<E extends Encrypted>(encrypted: E) {
+  const decrypted = encrypted; // replace with actual decryption
+  return revertEncrypt(encrypted, decrypted);
+}
+
+/** --------------------------
+ * Usage: encode then encrypt a value
+ * -------------------------- */
+
+const value = 'some value';
+
+// apply
+const encoded = encode(value);
+const encrypted = encrypt(encoded);
+
+// revert
+const decrypted = decrypt(encrypted);
+const orignalValue = decode(decrypted);
+
+// if you tried to decode for example before decrypting:
+const originalValue = decode(encrypted); // throws an error: Type 'typeof __Encrypted' is not assignable to type 'typeof __Encoded' in the last line.
+
+/** --------------------------
+ * Usage: safe-guards
+ * -------------------------- */
+
+// if we need encoded then encrypted string in our function we can just:
+function save(enc: Encrypted<Encoded<string>>) {
+  // handle save into db here
+}
+
+save(encrypted); // no errors
+save(encoded); // throws an error: Type 'string' is not assignable to type '{ __Phantom: { __Input: string; __Tag: unique symbol; __Label?: "Encoded value"; __Base?: Uint8Array<ArrayBufferLike>; }; }'.
+save('some string'); // throws an error: Argument of type 'string' is not assignable to parameter of type '{ __Phantom: { __Input: { __Phantom: { __Input: string; __Tag: unique symbol; __Label?: "Encoded value"; __Base?: Uint8Array<ArrayBufferLike>; }; }; __Tag: unique symbol; __Label?: "Encrypted value"; __Base?: Uint8Array<...>; }; }'.
+```
+
+Also it can be used in one-way transformations (e.g. `Hashed`):
+
+```ts
+import { Transformation, assertors } from '@vicin/phantom';
+
+declare const __Hashed: unique symbol;
+type Hashed<I = unknown> = Transformation.Declare<
+  I,
+  typeof __Hashed,
+  'Hashed value',
+  string
+>;
+const applyHash = assertors.applyTransformation<Hashed>();
+
+function hash<V>(value: V) {
+  const hashed = value as string; // replace with actual hash
+  return applyHash(value, hashed);
+}
+```
+
+---
+
+## Sigil
+
+`Sigil` is another lightweight TypeScript library I created for **nominal identity on classes**, providing compile-time branding and reliable runtime type checks. It solves the unreliability of `instanceof` in monorepos, bundled/HMR environments (where classes can duplicate), and manual branding boilerplate in DDD by using `symbols`, `lineages`, and a `centralized registry` for stable identity across codebases.
+
+`Sigil` works seamlessly in conjunction with `Phantom`,use `Phantom` for nominal typing on primitives/objects (type-only metadata), and `Sigil` for classes. Together, they enable comprehensive domain modeling: e.g., a Phantom-branded `UserId` could be a property in a Sigil-branded `User` class, combining zero-runtime primitive safety with robust class-level checks.
+
+- GitHub: **[@sigil](https://github.com/ZiadTaha62/sigil)**
+- NPM: **[@sigil](https://www.npmjs.com/package/@vicin/sigil)**
+
+---
+
+## Contributing
+
+Any contributions you make are **greatly appreciated**.
+
+Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+## Author
+
+Built with ❤️ by **Ziad Taha**.
+
+- GitHub: [@ZiadTaha62](https://github.com/ZiadTaha62)
+- NPM: [@ziadtaha62](https://www.npmjs.com/~ziadtaha62)
+- Vicin: [@vicin](https://www.npmjs.com/org/vicin)