lay-sing 0.1.2 → 0.2.1

package/README.md

@@ -1,18 +1,16 @@
-| English | [简体中文](./README-zh.md) |
-| ------- | -------------------------- |
+[![GitHub License](https://img.shields.io/github/license/Leawind/lay-sing)](https://github.com/Leawind/lay-sing?tab=MIT-1-ov-file)
+[![NPM Version](https://img.shields.io/npm/v/lay-sing?style=flat&logo=npm)](https://www.npmjs.com/package/lay-sing)
+[![JSR Version](https://jsr.io/badges/@leawind/lay-sing)](https://jsr.io/@leawind/lay-sing)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Leawind/lay-sing/verify.yaml?branch=main&logo=github-actions&label=test)](https://github.com/Leawind/lay-sing/actions/workflows/verify.yaml)
 
-# `lay-sing`
+# Lay-Sing
 
 TypeScript utilities for compile-time type testing and utility types
 
-## What is it
-
-1. **Testing Utilities**
-
 ```ts
 // They do nothing at runtime
 expect<never>().toBe<never>().success
-expect<never>().toBeNever // alias for above
+expect<never>().toBeNever // alias for the above
 expect<never>().toBe<'should fail'>().fail
 
 // Type Error: Property 'success' does not exist on type '{ fail: void; }'.
@@ -20,50 +18,59 @@ expect<never>().toBe<'should fail'>().success
 //                                    ^^^^^^^
 ```
 
-1. **Type Manipulation Tools**
+> [!TIP]
+>
+> I know this library is quite simple and serves a specific purpose, so one of its API design principles is to minimize the cognitive load for users. You just need to remember to **start with an `expect<>()` call** and **end with some property access**. Leave the rest to editor suggestions and inline documentation.
+
+## Install & Import
+
+<details>
+<summary>NPM</summary>
+
+```sh
+npm i -D lay-sing
+```
 
 ```ts
-// Result is 'Bob'
-type Result = Switch<2, [
-  Case<1, 'Alice'>,
-  Case<2, 'Bob'>,
-  Case<3, 'Charlie'>,
-], DefaultCase<'Unknown'>>
+import { expect } from 'lay-sing/test-utils'
 ```
 
-## Install
+</details>
 
-> This lib is published to both [NPM](https://www.npmjs.com/package/lay-sing) and [JSR](https://jsr.io/@leawind/lay-sing)
+<details>
+<summary>Deno</summary>
 
-### NPM
+### From NPM
 
 ```sh
-npm i -D lay-sing
+deno add npm:lay-sing
 ```
 
 ```ts
-import type { Same } from 'lay-sing'
 import { expect } from 'lay-sing/test-utils'
 ```
 
-### Deno (JSR)
+### From JSR
+
+This library is also published to [JSR (`@leawind/lay-sing`)](https://jsr.io/@leawind/lay-sing)
 
 ```sh
-deno add jsr:@leawind/lay-sing
+deno add @leawind/lay-sing
 ```
 
 ```ts
-import type { Same } from '@leawind/lay-sing'
 import { expect } from '@leawind/lay-sing/test-utils'
 ```
 
-Or Import directly:
+### From Latest commit
 
 ```ts
-import type { Same } from 'jsr:@leawind/lay-sing@^0.1'
-import { expect } from 'jsr:@leawind/lay-sing@^0.1/test-utils'
+import { expect } from 'https://raw.githubusercontent.com/Leawind/lay-sing/refs/heads/main/src/test-utils/index.ts'
+import { Exact } from 'https://raw.githubusercontent.com/Leawind/lay-sing/refs/heads/main/src/main/index.ts'
 ```
 
+</details>
+
 ---
 
 ## Usage
@@ -71,10 +78,10 @@ import { expect } from 'jsr:@leawind/lay-sing@^0.1/test-utils'
 ### Testing Utilities
 
 ```ts
-import { compare, expect, NOOP } from 'lay-sing/test-utils'
+import { expect } from 'lay-sing/test-utils'
 ```
 
-The `test-utils` module provides utilities for **compile-time** type validation. These utilities have **no runtime effect** — they always return a special [`NOOP`](https://jsr.io/@leawind/lay-sing/doc/test-utils/~/NOOP) value that safely supports almost any property access or method call.
+The `test-utils` module provides utilities for **compile-time** type validation. These utilities have **no runtime impact** — they always return a special [`NOOP`](https://jsr.io/@leawind/lay-sing/doc/test-utils/~/NOOP) value that safely supports almost any property access or method call.
 
 A typical type test statement follows this pattern:
 
@@ -84,63 +91,76 @@ expect<ActualType>().toBe<ExpectedType>().success
 
 - It starts with a function call like `expect<T>()` or `compare<T, U>()`
 - It ends with a property like `.success` or `.fail`
-- A **type error occurs only if the assertion fails**, helping you catch incorrect types at compile time
-- At runtime, the function always returns the actual value `NOOP`, which performs **no operation**. It can be accessed, called, or chained indefinitely without throwing
+- Type error occurs only if the assertion fails
+
+> [!CAUTION]
+>
+> Only statements ending with property access are type assertions. Without property access, type error may never occur:
+>
+> ```diff
+> - expect<true>().toBe<false>()         // Type error never occur
+> + expect<true>().toBe<false>().success // Type Error: Property 'success' does not exist on type '{ fail: void; }'.
+> ```
+
+At runtime, the function always returns the `NOOP` object, which performs **no operation**. It can be accessed, called, or chained indefinitely without throwing errors.
 
 #### Common Usage
 
 ```ts
-// Exact equality
-expect<A>().toBe<B>().success // Passes only if A and B are identical
-
-// Subtype check
-expect<A>().toExtend<B>().success // Passes if A extends B
+// Passes only if A and B are identical
+expect<keyof { a: 2 }>().toBe<'a'>().success
 
-// Property existence
-expect<{ name: string }>().toHaveProperty<'name'>().success
+// Passes if A extends B
+expect<12138>().toExtend<number>().success
 
-// Primitive checks
-expect<true>().toBeTrue.success
-expect<'hello'>().toExtendString.success
+// Passes if mutually assignable
+expect<{ a: 1; b: 2 }>().toEqual<{ a: 1 } & { b: 2 }>().success
 
-// Type comparison
-compare<A, B>().same // Available only if A ≡ B
-compare<A, B>().different // Available only if A ≠ B
+// Test property existence
+expect<{ name: string }>().toHaveKey<'name'>().success
 ```
 
-> [!TIP]
->
-> There's no need to memorize the full API.
->
-> Your editor will show inline documentation and auto-completion for all available methods and properties
+Aliases:
+
+```ts
+expect<never>().toBe<never>().success
+expect<never>().toBeNever
+
+expect<'hello'>().toExtend<string>().success
+expect<'hello'>().toExtendString
+```
 
 #### NOOP
 
-A `Proxy`-based no-op object:
+A `Proxy`-based no-op object with the following behavior:
 
-- Most accesses return itself.
-- `toString()` returns `"[NOOP]"`.
+- Most property/method accesses return the NOOP object itself.
+- `.toString()`, `.valueOf()` returns string `"[NOOP]"`.
 - Not thenable (`then` is `undefined`).
 
+It's used as returned value of `expect()` and `compare()`.
+
 ```ts
-NOOP.foo.bar().baz.qux // safe, returns NOOP
+expect().foo.bar().baz.qux // Safe, returns NOOP
 String(NOOP) // "[NOOP]"
-await NOOP // does not await (not thenable)
+await NOOP // Does not await (not thenable)
 ```
 
 ### Type Tools
 
-The main entry point provides a collection of utility types for common type-level programming tasks. All types are flat-exported from the main entry point — you don’t need to import from deep paths.
+The main entry point provides some utility types for common type-level programming tasks. All types are flat-exported from the main entry point — no need to import from nested paths.
 
 ```ts
-import type { Same } from 'lay-sing'
+import type { Exact } from 'lay-sing'
 ```
 
-> All types are documented — your editor will show inline documentation on hover
-
 ### Examples
 
 ```typescript
+// Test if exactly the same
+type False = Exact<{ a: 1 }, { a?: 1 }> // false
+type Yes = Exact<boolean, true | false, 'yes', 'no'> // 'yes'
+
 // Conditional Types
 type Result = If<true, 'yes', 'no'> // 'yes'
 
@@ -155,12 +175,4 @@ type PartialObj = DeepPartial<{ a: string; nested: { b: number } }>
 // { a?: string; nested?: { b?: number } }
 ```
 
-> [!NOTE]
->
-> [Full API documentation is available on JSR](https://jsr.io/@leawind/lay-sing/doc)
-
----
-
-> ## _Pronunciation of lay-sing_
->
-> _"lay-sing" mimics Mandarin "lèi xíng" ("type") — Say "LAY-sing" with a sharp "LAY" (like a command) followed by a rising "sing" (like a question)._
+[Full API documentation is available on JSR](https://jsr.io/@leawind/lay-sing/doc)

package/esm/main/async.d.ts

@@ -1,5 +1,13 @@
 /**
- * Represents a value that can be either T or a Promise of T
+ * Represents a value that can be either `T` or a Promise of `T`
+ *
+ * @template T - The underlying type that may or may not be wrapped in a Promise
+ *
+ * @example
+ * ```ts
+ * type StringOrPromise = Awaitable<string>
+ * // Equivalent to: string | Promise<string>
+ * ```
  */
 export type Awaitable<T> = Promise<T> | T;
 //# sourceMappingURL=async.d.ts.map

package/esm/main/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/main/async.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/main/async.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}

package/esm/main/async.js.map

@@ -1 +1 @@
-{"version":3,"file":"async.js","sourceRoot":"","sources":["../../src/main/async.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Represents a value that can be either T or a Promise of T\n */\nexport type Awaitable<T> = Promise<T> | T\n"]}
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../../src/main/async.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Represents a value that can be either `T` or a Promise of `T`\n *\n * @template T - The underlying type that may or may not be wrapped in a Promise\n *\n * @example\n * ```ts\n * type StringOrPromise = Awaitable<string>\n * // Equivalent to: string | Promise<string>\n * ```\n */\nexport type Awaitable<T> = Promise<T> | T\n"]}

package/esm/main/boolean.d.ts

@@ -1,36 +1,59 @@
 /**
- * ### Result
+ * Negates a boolean type
  *
- * - `never`: if `T` is `never`
- * - `boolean`: if `T` is `boolean` or `any`
- * - `false`: if `T` is `true`
- * - `true`: if `T` is `false`
+ * @template T - The boolean type to negate
  *
- * ### Examples
+ * @example
+ * ```ts
+ * import { expect } from '@leawind/lay-sing/test-utils'
  *
- * | `T`       | `Not<T>`  |
- * | --------- | --------- |
- * | `never`   | `never`    |
- * | `true`    | `false`   |
- * | `false`   | `true`    |
- * | `boolean` | `boolean` |
- * | `any`     | `boolean` |
+ * expect<Not<true>>().toBeFalse
+ * expect<Not<false>>().toBeTrue
+ * expect<Not<boolean>>().toBe<boolean>().success
+ * ```
  */
 export type Not<T extends boolean> = T extends true ? false : T extends false ? true : boolean;
 /**
- * - `never`: if anyone of A,B is `never`
- * - `boolean`: if anyone of A,B is `boolean` or `any`
- * - `true`: if both A,B are `true`
- * - `false`: otherwise
+ * Logical AND operation on two boolean types
+ *
+ * @template A - The first boolean type to compare
+ * @template B - The second boolean type to compare
+ *
+ * @example
+ * ```ts
+ * import { expect } from '@leawind/lay-sing/test-utils'
+ *
+ * expect<And<true, true>>().toBeTrue
+ * expect<And<true, false>>().toBeFalse
+ * expect<And<false, true>>().toBeFalse
+ * expect<And<false, false>>().toBeFalse
+ * expect<And<boolean, boolean>>().toBe<boolean>().success
+ * ```
  */
 export type And<A extends boolean, B extends boolean> = A extends never ? never : [B] extends [never] ? never : (A extends true ? (B extends true ? true : false) : false);
 /**
+ * Logical OR operation on two boolean types
+ *
+ * @template A - The first boolean type to compare
+ * @template B - The second boolean type to compare
+ *
  * ### Result
  *
- * - `never`: if anyone of A,B is `never`
- * - `boolean`: if anyone of A,B is `boolean` or `any`
- * - `false`: if both A,B are `false`
+ * - `never`: if either `A` or `B` is `never`
+ * - `boolean`: if either `A` or `B` is `boolean` or `any`
+ * - `false`: if both `A` and `B` are `false`
  * - `true`: otherwise
+ *
+ * @example
+ * ```ts
+ * import { expect } from '@leawind/lay-sing/test-utils'
+ *
+ * expect<Or<true, true>>().toBeTrue
+ * expect<Or<true, false>>().toBeTrue
+ * expect<Or<false, true>>().toBeTrue
+ * expect<Or<false, false>>().toBeFalse
+ * expect<Or<boolean, false>>().toBe<boolean>().success
+ * ```
  */
 export type Or<A extends boolean, B extends boolean> = [A] extends [never] ? never : [B] extends [never] ? never : [boolean] extends [A] ? boolean : [boolean] extends [B] ? boolean : true extends A ? true : true extends B ? true : false;
 //# sourceMappingURL=boolean.d.ts.map

package/esm/main/boolean.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boolean.d.ts","sourceRoot":"","sources":["../../src/main/boolean.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,OAAO,IAAI,CAAC,SAAS,IAAI,GAAG,KAAK,GACvD,CAAC,SAAS,KAAK,GAAG,IAAI,GACtB,OAAO,CAAA;AAEX;;;;;GAKG;AACH,MAAM,MAAM,GAAG,CACb,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,IACf,CAAC,SAAS,KAAK,GAAG,KAAK,GACvB,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAC3B,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,CAAA;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,EAAE,CACZ,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,IACf,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAC3B,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAC3B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,GAC/B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,GAC/B,IAAI,SAAS,CAAC,GAAG,IAAI,GACrB,IAAI,SAAS,CAAC,GAAG,IAAI,GACrB,KAAK,CAAA"}
+{"version":3,"file":"boolean.d.ts","sourceRoot":"","sources":["../../src/main/boolean.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,OAAO,IAAI,CAAC,SAAS,IAAI,GAAG,KAAK,GACvD,CAAC,SAAS,KAAK,GAAG,IAAI,GACtB,OAAO,CAAA;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,GAAG,CACb,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,IACf,CAAC,SAAS,KAAK,GAAG,KAAK,GACvB,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAC3B,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,EAAE,CACZ,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,IACf,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAC3B,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAC3B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,GAC/B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,GAC/B,IAAI,SAAS,CAAC,GAAG,IAAI,GACrB,IAAI,SAAS,CAAC,GAAG,IAAI,GACrB,KAAK,CAAA"}

package/esm/main/boolean.js.map

@@ -1 +1 @@
-{"version":3,"file":"boolean.js","sourceRoot":"","sources":["../../src/main/boolean.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * ### Result\n *\n * - `never`: if `T` is `never`\n * - `boolean`: if `T` is `boolean` or `any`\n * - `false`: if `T` is `true`\n * - `true`: if `T` is `false`\n *\n * ### Examples\n *\n * | `T`       | `Not<T>`  |\n * | --------- | --------- |\n * | `never`   | `never`    |\n * | `true`    | `false`   |\n * | `false`   | `true`    |\n * | `boolean` | `boolean` |\n * | `any`     | `boolean` |\n */\nexport type Not<T extends boolean> = T extends true ? false\n  : T extends false ? true\n  : boolean\n\n/**\n * - `never`: if anyone of A,B is `never`\n * - `boolean`: if anyone of A,B is `boolean` or `any`\n * - `true`: if both A,B are `true`\n * - `false`: otherwise\n */\nexport type And<\n  A extends boolean,\n  B extends boolean,\n> = A extends never ? never\n  : [B] extends [never] ? never\n  : (A extends true ? (B extends true ? true : false) : false)\n\n/**\n * ### Result\n *\n * - `never`: if anyone of A,B is `never`\n * - `boolean`: if anyone of A,B is `boolean` or `any`\n * - `false`: if both A,B are `false`\n * - `true`: otherwise\n */\nexport type Or<\n  A extends boolean,\n  B extends boolean,\n> = [A] extends [never] ? never\n  : [B] extends [never] ? never\n  : [boolean] extends [A] ? boolean\n  : [boolean] extends [B] ? boolean\n  : true extends A ? true\n  : true extends B ? true\n  : false\n"]}
+{"version":3,"file":"boolean.js","sourceRoot":"","sources":["../../src/main/boolean.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Negates a boolean type\n *\n * @template T - The boolean type to negate\n *\n * @example\n * ```ts\n * import { expect } from '@leawind/lay-sing/test-utils'\n *\n * expect<Not<true>>().toBeFalse\n * expect<Not<false>>().toBeTrue\n * expect<Not<boolean>>().toBe<boolean>().success\n * ```\n */\nexport type Not<T extends boolean> = T extends true ? false\n  : T extends false ? true\n  : boolean\n\n/**\n * Logical AND operation on two boolean types\n *\n * @template A - The first boolean type to compare\n * @template B - The second boolean type to compare\n *\n * @example\n * ```ts\n * import { expect } from '@leawind/lay-sing/test-utils'\n *\n * expect<And<true, true>>().toBeTrue\n * expect<And<true, false>>().toBeFalse\n * expect<And<false, true>>().toBeFalse\n * expect<And<false, false>>().toBeFalse\n * expect<And<boolean, boolean>>().toBe<boolean>().success\n * ```\n */\nexport type And<\n  A extends boolean,\n  B extends boolean,\n> = A extends never ? never\n  : [B] extends [never] ? never\n  : (A extends true ? (B extends true ? true : false) : false)\n\n/**\n * Logical OR operation on two boolean types\n *\n * @template A - The first boolean type to compare\n * @template B - The second boolean type to compare\n *\n * ### Result\n *\n * - `never`: if either `A` or `B` is `never`\n * - `boolean`: if either `A` or `B` is `boolean` or `any`\n * - `false`: if both `A` and `B` are `false`\n * - `true`: otherwise\n *\n * @example\n * ```ts\n * import { expect } from '@leawind/lay-sing/test-utils'\n *\n * expect<Or<true, true>>().toBeTrue\n * expect<Or<true, false>>().toBeTrue\n * expect<Or<false, true>>().toBeTrue\n * expect<Or<false, false>>().toBeFalse\n * expect<Or<boolean, false>>().toBe<boolean>().success\n * ```\n */\nexport type Or<\n  A extends boolean,\n  B extends boolean,\n> = [A] extends [never] ? never\n  : [B] extends [never] ? never\n  : [boolean] extends [A] ? boolean\n  : [boolean] extends [B] ? boolean\n  : true extends A ? true\n  : true extends B ? true\n  : false\n"]}

package/esm/main/control.d.ts

@@ -1,88 +1,112 @@
-import type { Same } from './type/compare.js';
+import type { Exact } from './type/compare.js';
 /**
- * Conditional type - returns `T` if condition `C` is true, otherwise returns `F`
+ * Conditional type - returns `Yes` if condition `Condition` is true, otherwise returns `No`
  *
- * ### Result
- *
- * - `never`: if `C` is `never`
- * - `T`: if `C` is `true`
- * - `F`: if `C` is `false`
- *
- * ### Examples
+ * @template Condition - The boolean condition to check
+ * @template Yes - The type to return if condition is true
+ * @template No - The type to return if condition is false (defaults to `never`)
  *
+ * @example
  * ```ts
  * type Result = If<true, 'yes', 'no'> // 'yes'
  * type Result2 = If<false, 'yes', 'no'> // 'no'
- * type NeverResult = If<never, 'yes', 'no'> // never
+ * type BoolResult = If<boolean, 'yes', 'no'> // boolean
  * ```
  */
-export type If<C extends boolean, T, F = never> = [C] extends [never] ? never : C extends true ? T : F;
+export type If<Condition extends boolean, Yes, No = never> = Condition extends true ? Yes : No;
 /**
- * Conditional type - returns `T` if condition `C` is false, otherwise returns `F`
+ * Conditional type - returns `Yes` if condition `Condition` is false, otherwise returns `No`
  *
- * ### Result
+ * @template Condition - The boolean condition to check
+ * @template Yes - The type to return if condition is false
+ * @template No - The type to return if condition is true (defaults to `never`)
  *
- * - `never`: if `C` is `never`
- * - `T`: if `C` is `false`
- * - `F`: if `C` is `true`
+ * ### Result
  *
- * ### Examples
+ * - `never`: if `Condition` is `never`
+ * - `Yes`: if `Condition` is `false`
+ * - `No`: if `Condition` is `true`
  *
+ * @example
  * ```ts
  * type Result = IfFalse<false, 'yes', 'no'> // 'yes'
  * type Result2 = IfFalse<true, 'yes', 'no'> // 'no'
- * type NeverResult = IfFalse<never, 'yes', 'no'> // never
+ * type BoolResult = IfFalse<boolean, 'yes', 'no'> // boolean
  * ```
  */
-export type IfFalse<C extends boolean, T, F = never> = [C] extends [never] ? never : C extends false ? T : F;
+export type IfFalse<Condition extends boolean, Yes, No = never> = Condition extends false ? Yes : No;
 /**
- * Used with:
- * - {@link Switch}
- * - {@link SwitchExtends}
+ * Case tuple type used with `SwitchExact` and `SwitchExtends`
+ *
+ * @template T - The condition type to match against
+ * @template Result - The result type to return if match is found
+ *
+ * @example
+ * ```ts
+ * type MyCase = Case<1, 'one'>
+ * // Equivalent to: [1, 'one']
+ * ```
+ *
+ * @see SwitchExact
  */
-export type Case<T = unknown, Return = unknown> = [T, Return];
+export type Case<T = unknown, Result = unknown> = [T, Result];
 /**
- * Used with:
- *
- * - {@link Switch}
- * - {@link SwitchExtends}
+ * Default case type used with `SwitchExact` and `SwitchExtends`
  *
- * ### Examples
+ * @template T - The default result type
  *
+ * @example
  * ```ts
- * type NameMap<id> = Switch<id, [
- *   Case<1, 'Alice'>,
- *   Case<2, 'Bob'>,
- *   Case<3, 'Charlie'>,
+ * type NameMap<id> = SwitchExact<id, [
+ *   [1, 'Alice'],
+ *   [2, 'Bob'],
  * ], DefaultCase<'Steve'>>
  * ```
+ *
+ * @see SwitchExact
  */
 export type DefaultCase<T> = T;
 /**
- * ### Examples
+ * Switch type that uses exact matching logic
+ *
+ * **⚠️Important:** `T` parameter is not distributive. When `T` is a union type, it does not check each member separately.
  *
+ * @template T - The type to match against cases
+ * @template Cases - Array of case tuples, each tuple has the form [Condition, Result]
+ * @template Default - Default result if no exact match is found (defaults to `never`)
+ *
+ * @example
  * ```ts
- * type Result = Switch<2, [
- *   Case<1, 'Alice'>,
- *   Case<2, 'Bob'>,
- *   Case<3, 'Charlie'>,
+ * type Result = SwitchExact<2, [
+ *   [1, 'Alice'],
+ *   [2, 'Bob'],
+ *   [3, 'Charlie'],
  * ], DefaultCase<'Steve'>>
  *
  * // Result: 'Bob'
  * ```
  */
-export type Switch<T, Cases extends readonly Case[], Default = never> = Cases extends [infer First, ...infer Rest] ? (First extends [infer C, infer R] ? (Same<T, C> extends true ? R : (Switch<T, Rest extends readonly Case[] ? Rest : never, Default>)) : (never)) : Default;
+export type SwitchExact<T, Cases extends readonly [unknown, unknown][], Default = never> = Cases extends [infer First, ...infer Rest] ? (First extends [infer Condition, infer Result] ? (Exact<T, Condition> extends true ? Result : (SwitchExact<T, Rest extends readonly [unknown, unknown][] ? Rest : never, Default>)) : (never)) : Default;
 /**
- * Switch type that uses 'extends' logic instead of 'Same' logic
+ * Switch type that uses 'extends' logic instead of 'Exact' logic
+ *
+ * **⚠️Important:** `T` parameter is not distributive. When `T` is a union type, it does not check each member separately.
  *
- * ### Examples
+ * @template T - The type to match against cases
+ * @template Cases - Array of case tuples, each tuple has the form [Condition, Result]
+ * @template Default - Default result if no match is found (defaults to `never`)
+ *
+ * @example
  * ```ts
- * type Result = SwitchExtends<string | number, [
- *   Case<string, 'string type'>,
- *   Case<number, 'number type'>,
- * ], 'other'>
- * // Result: 'string type' | 'number type'
+ * import { expect } from '@leawind/lay-sing/test-utils'
+ *
+ * expect<
+ *   SwitchExtends<string, [
+ *     [number, boolean],
+ *     [string, boolean],
+ *   ], Error>
+ * >().toBe<boolean>().success
  * ```
  */
-export type SwitchExtends<T, Cases extends readonly Case[], Default = never> = Cases extends [infer First, ...infer Rest] ? (First extends [infer C, infer R] ? ([T] extends [C] ? R : SwitchExtends<T, Rest extends readonly Case[] ? Rest : never, Default>) : never) : Default;
+export type SwitchExtends<T, Cases extends readonly [unknown, unknown][], Default = never> = Cases extends [infer First, ...infer Rest] ? (First extends [infer C, infer R] ? ([T] extends [C] ? R : SwitchExtends<T, Rest extends readonly [unknown, unknown][] ? Rest : never, Default>) : never) : Default;
 //# sourceMappingURL=control.d.ts.map

package/esm/main/control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/main/control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,EAAE,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GACzE,CAAC,SAAS,IAAI,GAAG,CAAC,GAClB,CAAC,CAAA;AAEL;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAC9E,CAAC,SAAS,KAAK,GAAG,CAAC,GACnB,CAAC,CAAA;AAEL;;;;GAIG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;AAC7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAA;AAE9B;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,MAAM,CAChB,CAAC,EACD,KAAK,SAAS,SAAS,IAAI,EAAE,EAC7B,OAAO,GAAG,KAAK,IACb,KAAK,SAAS,CAAC,MAAM,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAC7C,KAAK,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC5B,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,SAAS,SAAS,IAAI,EAAE,GAAG,IAAI,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GACjG,CAAC,KAAK,CAAC,CACZ,GACC,OAAO,CAAA;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,CACvB,CAAC,EACD,KAAK,SAAS,SAAS,IAAI,EAAE,EAC7B,OAAO,GAAG,KAAK,IACb,KAAK,SAAS,CAAC,MAAM,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAC7C,KAAK,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC5B,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,IAAI,SAAS,SAAS,IAAI,EAAE,GAAG,IAAI,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC,GAC9F,KAAK,CACV,GACC,OAAO,CAAA"}
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/main/control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,EAAE,CAAC,SAAS,SAAS,OAAO,EAAE,GAAG,EAAE,EAAE,GAAG,KAAK,IAAI,SAAS,SAAS,IAAI,GAAG,GAAG,GAAG,EAAE,CAAA;AAE9F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,OAAO,CAAC,SAAS,SAAS,OAAO,EAAE,GAAG,EAAE,EAAE,GAAG,KAAK,IAAI,SAAS,SAAS,KAAK,GAAG,GAAG,GAAG,EAAE,CAAA;AAEpG;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;AAE7D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,CACrB,CAAC,EACD,KAAK,SAAS,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAC3C,OAAO,GAAG,KAAK,IACb,KAAK,SAAS,CAAC,MAAM,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAC7C,KAAK,SAAS,CAAC,MAAM,SAAS,EAAE,MAAM,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,SAAS,IAAI,GAAG,MAAM,GACpF,CAAC,WAAW,CAAC,CAAC,EAAE,IAAI,SAAS,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GACvF,CAAC,KAAK,CAAC,CACZ,GACC,OAAO,CAAA;AAEX;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,aAAa,CACvB,CAAC,EACD,KAAK,SAAS,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAC3C,OAAO,GAAG,KAAK,IACb,KAAK,SAAS,CAAC,MAAM,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAC7C,KAAK,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC5B,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,IAAI,SAAS,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC,GAC5G,KAAK,CACV,GACC,OAAO,CAAA"}

package/esm/main/control.js.map

@@ -1 +1 @@
-{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/main/control.ts"],"names":[],"mappings":"","sourcesContent":["import type { Same } from './type/compare.js'\n\n/**\n * Conditional type - returns `T` if condition `C` is true, otherwise returns `F`\n *\n * ### Result\n *\n * - `never`: if `C` is `never`\n * - `T`: if `C` is `true`\n * - `F`: if `C` is `false`\n *\n * ### Examples\n *\n * ```ts\n * type Result = If<true, 'yes', 'no'> // 'yes'\n * type Result2 = If<false, 'yes', 'no'> // 'no'\n * type NeverResult = If<never, 'yes', 'no'> // never\n * ```\n */\nexport type If<C extends boolean, T, F = never> = [C] extends [never] ? never\n  : C extends true ? T\n  : F\n\n/**\n * Conditional type - returns `T` if condition `C` is false, otherwise returns `F`\n *\n * ### Result\n *\n * - `never`: if `C` is `never`\n * - `T`: if `C` is `false`\n * - `F`: if `C` is `true`\n *\n * ### Examples\n *\n * ```ts\n * type Result = IfFalse<false, 'yes', 'no'> // 'yes'\n * type Result2 = IfFalse<true, 'yes', 'no'> // 'no'\n * type NeverResult = IfFalse<never, 'yes', 'no'> // never\n * ```\n */\nexport type IfFalse<C extends boolean, T, F = never> = [C] extends [never] ? never\n  : C extends false ? T\n  : F\n\n/**\n * Used with:\n * - {@link Switch}\n * - {@link SwitchExtends}\n */\nexport type Case<T = unknown, Return = unknown> = [T, Return]\n/**\n * Used with:\n *\n * - {@link Switch}\n * - {@link SwitchExtends}\n *\n * ### Examples\n *\n * ```ts\n * type NameMap<id> = Switch<id, [\n *   Case<1, 'Alice'>,\n *   Case<2, 'Bob'>,\n *   Case<3, 'Charlie'>,\n * ], DefaultCase<'Steve'>>\n * ```\n */\nexport type DefaultCase<T> = T\n\n/**\n * ### Examples\n *\n * ```ts\n * type Result = Switch<2, [\n *   Case<1, 'Alice'>,\n *   Case<2, 'Bob'>,\n *   Case<3, 'Charlie'>,\n * ], DefaultCase<'Steve'>>\n *\n * // Result: 'Bob'\n * ```\n */\nexport type Switch<\n  T,\n  Cases extends readonly Case[],\n  Default = never,\n> = Cases extends [infer First, ...infer Rest] ? (\n    First extends [infer C, infer R]\n      ? (Same<T, C> extends true ? R : (Switch<T, Rest extends readonly Case[] ? Rest : never, Default>))\n      : (never)\n  )\n  : Default\n\n/**\n * Switch type that uses 'extends' logic instead of 'Same' logic\n *\n * ### Examples\n * ```ts\n * type Result = SwitchExtends<string | number, [\n *   Case<string, 'string type'>,\n *   Case<number, 'number type'>,\n * ], 'other'>\n * // Result: 'string type' | 'number type'\n * ```\n */\nexport type SwitchExtends<\n  T,\n  Cases extends readonly Case[],\n  Default = never,\n> = Cases extends [infer First, ...infer Rest] ? (\n    First extends [infer C, infer R]\n      ? ([T] extends [C] ? R : SwitchExtends<T, Rest extends readonly Case[] ? Rest : never, Default>)\n      : never\n  )\n  : Default\n"]}
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/main/control.ts"],"names":[],"mappings":"","sourcesContent":["import type { Exact } from './type/compare.js'\n\n/**\n * Conditional type - returns `Yes` if condition `Condition` is true, otherwise returns `No`\n *\n * @template Condition - The boolean condition to check\n * @template Yes - The type to return if condition is true\n * @template No - The type to return if condition is false (defaults to `never`)\n *\n * @example\n * ```ts\n * type Result = If<true, 'yes', 'no'> // 'yes'\n * type Result2 = If<false, 'yes', 'no'> // 'no'\n * type BoolResult = If<boolean, 'yes', 'no'> // boolean\n * ```\n */\nexport type If<Condition extends boolean, Yes, No = never> = Condition extends true ? Yes : No\n\n/**\n * Conditional type - returns `Yes` if condition `Condition` is false, otherwise returns `No`\n *\n * @template Condition - The boolean condition to check\n * @template Yes - The type to return if condition is false\n * @template No - The type to return if condition is true (defaults to `never`)\n *\n * ### Result\n *\n * - `never`: if `Condition` is `never`\n * - `Yes`: if `Condition` is `false`\n * - `No`: if `Condition` is `true`\n *\n * @example\n * ```ts\n * type Result = IfFalse<false, 'yes', 'no'> // 'yes'\n * type Result2 = IfFalse<true, 'yes', 'no'> // 'no'\n * type BoolResult = IfFalse<boolean, 'yes', 'no'> // boolean\n * ```\n */\nexport type IfFalse<Condition extends boolean, Yes, No = never> = Condition extends false ? Yes : No\n\n/**\n * Case tuple type used with `SwitchExact` and `SwitchExtends`\n *\n * @template T - The condition type to match against\n * @template Result - The result type to return if match is found\n *\n * @example\n * ```ts\n * type MyCase = Case<1, 'one'>\n * // Equivalent to: [1, 'one']\n * ```\n *\n * @see SwitchExact\n */\nexport type Case<T = unknown, Result = unknown> = [T, Result]\n\n/**\n * Default case type used with `SwitchExact` and `SwitchExtends`\n *\n * @template T - The default result type\n *\n * @example\n * ```ts\n * type NameMap<id> = SwitchExact<id, [\n *   [1, 'Alice'],\n *   [2, 'Bob'],\n * ], DefaultCase<'Steve'>>\n * ```\n *\n * @see SwitchExact\n */\nexport type DefaultCase<T> = T\n\n/**\n * Switch type that uses exact matching logic\n *\n * **⚠️Important:** `T` parameter is not distributive. When `T` is a union type, it does not check each member separately.\n *\n * @template T - The type to match against cases\n * @template Cases - Array of case tuples, each tuple has the form [Condition, Result]\n * @template Default - Default result if no exact match is found (defaults to `never`)\n *\n * @example\n * ```ts\n * type Result = SwitchExact<2, [\n *   [1, 'Alice'],\n *   [2, 'Bob'],\n *   [3, 'Charlie'],\n * ], DefaultCase<'Steve'>>\n *\n * // Result: 'Bob'\n * ```\n */\nexport type SwitchExact<\n  T,\n  Cases extends readonly [unknown, unknown][],\n  Default = never,\n> = Cases extends [infer First, ...infer Rest] ? (\n    First extends [infer Condition, infer Result] ? (Exact<T, Condition> extends true ? Result\n        : (SwitchExact<T, Rest extends readonly [unknown, unknown][] ? Rest : never, Default>))\n      : (never)\n  )\n  : Default\n\n/**\n * Switch type that uses 'extends' logic instead of 'Exact' logic\n *\n * **⚠️Important:** `T` parameter is not distributive. When `T` is a union type, it does not check each member separately.\n *\n * @template T - The type to match against cases\n * @template Cases - Array of case tuples, each tuple has the form [Condition, Result]\n * @template Default - Default result if no match is found (defaults to `never`)\n *\n * @example\n * ```ts\n * import { expect } from '@leawind/lay-sing/test-utils'\n *\n * expect<\n *   SwitchExtends<string, [\n *     [number, boolean],\n *     [string, boolean],\n *   ], Error>\n * >().toBe<boolean>().success\n * ```\n */\nexport type SwitchExtends<\n  T,\n  Cases extends readonly [unknown, unknown][],\n  Default = never,\n> = Cases extends [infer First, ...infer Rest] ? (\n    First extends [infer C, infer R]\n      ? ([T] extends [C] ? R : SwitchExtends<T, Rest extends readonly [unknown, unknown][] ? Rest : never, Default>)\n      : never\n  )\n  : Default\n"]}

package/esm/main/doc.d.ts

@@ -1,30 +1,56 @@
 /**
- * Append documentation or auxiliary metadata to type `A`
+ * Append documentation or auxiliary metadata to type `T`
  * without changing its shape.
  *
- * This type intersects `Doc` onto `A`, but only keeps the keys
- * originally defined in `A`. As a result:
+ * This type intersects `Doc` onto `T`, but only keeps the keys
+ * originally defined in `T`. As a result:
  *
  * - `Doc` cannot introduce new properties
- * - Existing properties in `A` are preserved
+ * - Existing properties in `T` are preserved
  * - `Doc` may further constrain or annotate existing properties
  *
  * This is typically used to attach JSDoc comments, branding,
  * or editor-only metadata to an existing type while keeping
  * its public structure intact.
+ *
+ * @template T - The target type to append documentation to
+ * @template Doc - The documentation or metadata type to append
+ *
+ * @example
+ * ```ts
+ * import { expect } from '@leawind/lay-sing/test-utils'
+ *
+ * type User = { name: string; age: number }
+ * type UserWithDoc = AppendDoc<User, { name: string }>
+ *
+ * expect<UserWithDoc>().toBe<User>().success
+ * ```
  */
 export type AppendDoc<T, Doc> = Pick<T & Doc, keyof T>;
 /**
- * Prepend documentation or auxiliary metadata to type `A`
+ * Prepend documentation or auxiliary metadata to type `T`
  * without changing its shape.
  *
  * This is similar to {@link AppendDoc}, but the intersection order
- * is reversed (`Doc & A`), which can affect how property types,
+ * is reversed (`Doc & T`), which can affect how property types,
  * documentation, and hover information are presented by tooling.
  *
  * In practice, this allows `Doc` to act as a non-invasive,
- * descriptive layer while ensuring `A` remains the authoritative
+ * descriptive layer while ensuring `T` remains the authoritative
  * source of truth for property types.
+ *
+ * @template T - The target type to prepend documentation to
+ * @template Doc - The documentation or metadata type to prepend
+ *
+ * @example
+ * ```ts
+ * import { expect } from '@leawind/lay-sing/test-utils'
+ *
+ * type User = { name: string; age: number }
+ * type UserWithDoc = PrependDoc<User, { age: number }>
+ *
+ * expect<UserWithDoc>().toBe<User>().success
+ * ```
  */
 export type PrependDoc<T, Doc> = Pick<Doc & T, keyof T>;
 //# sourceMappingURL=doc.d.ts.map

package/esm/main/doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/main/doc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,CAAC,CAAC,CAAA;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA"}
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/main/doc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,CAAC,CAAC,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA"}