@guillaume-docquier/tools-ts 7.5.2 → 8.0.0

package/README.md

@@ -69,19 +69,19 @@ pseudo-random sequences.
 
 These exports are type-only helpers for common TypeScript modeling problems.
 
-| Export                                     | What it is                                                        | Use it when                                                                                |
-| ------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `Branded`, `branded`                       | A nominal typing helper plus a runtime no-op for branding values. | Structurally identical values need distinct domain types, such as separate ID kinds.       |
-| `Unbranded`                                | Removes a brand from a type.                                      | An API accepts the underlying value of a branded type.                                     |
-| `UnbrandedProperties`                      | Removes brands from an object's property types.                   | An object input should use raw values for branded fields.                                  |
-| `ConstructorType`                          | A type for class constructors.                                    | A function accepts a class and later uses `new` or `instanceof` against it.                |
-| `EnumKeyType`, `EnumValueType`, `EnumType` | Broad shapes for enum-like objects.                               | You are writing generic utilities that operate on TypeScript enums or const-object enums.  |
-| `Enumify`                                  | Converts a const object into a union of its values.               | A project avoids TypeScript `enum` but wants enum-like ergonomics from `as const` objects. |
-| `ValueOf`                                  | Produces a union of an object's value types.                      | You need the values of a lookup object as a type.                                          |
-| `Prettify`                                 | Re-expands an object type for easier editor hovers.               | Intersections or mapped types are correct but hard to read in tooling.                     |
-| `OmitOverUnion`                            | Applies `Omit` distributively across union members.               | Native `Omit` collapses a discriminated union in a way that loses member-specific fields.  |
-| `PartialProperties`                        | Makes selected object properties partial, not the whole object.   | Only nested property objects should become partial while the parent shape stays required.  |
-| `Mutable`                                  | Removes `readonly` from selected properties.                      | You have a narrow, deliberate mutation need. Avoid this unless there is no cleaner model.  |
+| Export                                     | What it is                                                                   | Use it when                                                                                |
+| ------------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `Branded<TBrand, TType>`, `branded`        | A composable nominal typing helper plus a runtime no-op for branding values. | Structurally identical values need distinct domain types.                                  |
+| `Unbranded`                                | Removes a brand from a type.                                                 | An API accepts the underlying value of a branded type.                                     |
+| `UnbrandedProperties`                      | Removes brands from an object's property types.                              | An object input should use raw values for branded fields.                                  |
+| `ConstructorType`                          | A type for class constructors.                                               | A function accepts a class and later uses `new` or `instanceof` against it.                |
+| `EnumKeyType`, `EnumValueType`, `EnumType` | Broad shapes for enum-like objects.                                          | You are writing generic utilities that operate on TypeScript enums or const-object enums.  |
+| `Enumify`                                  | Converts a const object into a union of its values.                          | A project avoids TypeScript `enum` but wants enum-like ergonomics from `as const` objects. |
+| `ValueOf`                                  | Produces a union of an object's value types.                                 | You need the values of a lookup object as a type.                                          |
+| `Prettify`                                 | Re-expands an object type for easier editor hovers.                          | Intersections or mapped types are correct but hard to read in tooling.                     |
+| `OmitOverUnion`                            | Applies `Omit` distributively across union members.                          | Native `Omit` collapses a discriminated union in a way that loses member-specific fields.  |
+| `PartialProperties`                        | Makes selected object properties partial, not the whole object.              | Only nested property objects should become partial while the parent shape stays required.  |
+| `Mutable`                                  | Removes `readonly` from selected properties.                                 | You have a narrow, deliberate mutation need. Avoid this unless there is no cleaner model.  |
 
 ### Logging
 

package/dist/Brand.d.ts

@@ -1,13 +1,15 @@
 declare const brand: unique symbol;
 declare const baseType: unique symbol;
-type AnyBrand = Branded<unknown, unknown>;
+type AnyBrand = {
+    [baseType]: unknown;
+};
 type TypeOf<TBrand extends AnyBrand> = TBrand[typeof baseType];
 /**
  * Type utility to create branded types.
  *
  * @example
  * ```ts
- * type UserId = Branded<string, "userId">
+ * type UserId = Branded<"UserId", string>
  * function getUser(userId: UserId): User {}
  *
  * const str = "a string"
@@ -16,9 +18,21 @@ type TypeOf<TBrand extends AnyBrand> = TBrand[typeof baseType];
  * getUser(str) // S2345: Argument of type string is not assignable to parameter of type UserId
  * getUser(userId) // works!
  * ```
+ *
+ * Brands can be composed with a normal type intersection.
+ *
+ * ```ts
+ * type PositiveNumber = Branded<"PositiveNumber", number>
+ * type Integer = Branded<"Integer", number>
+ * type PositiveInteger = PositiveNumber & Integer
+ *
+ * const positiveNumber: PositiveNumber = branded<PositiveInteger>(1)
+ * const integer: Integer = branded<PositiveInteger>(1)
+ * const positiveInteger: PositiveInteger  = branded<PositiveInteger>(1)
+ * ```
  */
-export type Branded<TType, TBrand> = TType & {
-    [brand]: TBrand;
+export type Branded<TBrand, TType> = TType & {
+    readonly [brand]: (value: TBrand) => TBrand;
 } & {
     [baseType]: TType;
 };
@@ -31,7 +45,9 @@ export declare function branded<TBrand extends AnyBrand>(value: TypeOf<TBrand>):
  * Removes the brand from a branded type while leaving other types unchanged.
  * Usually useful for tests when you want to accept unbranded arguments and brand them to alleviate test code.
  */
-export type Unbranded<T> = T extends Branded<infer Base, infer _Tag> ? Base : T;
+export type Unbranded<T> = T extends {
+    [baseType]: infer Base;
+} ? Base : T;
 /**
  * Removes brands from an object's property types.
  * Usually useful for tests when you want to accept unbranded arguments and brand them to alleviate test code.

package/dist/Brand.js.map

@@ -1 +1 @@
-{"version":3,"file":"Brand.js","sourceRoot":"","sources":["../src/Brand.ts"],"names":[],"mappings":"AAuBA;;;GAGG;AACH,MAAM,UAAU,OAAO,CAA0B,KAAqB;IACpE,6HAA6H;IAC7H,OAAO,KAAe,CAAA;AACxB,CAAC"}
+{"version":3,"file":"Brand.js","sourceRoot":"","sources":["../src/Brand.ts"],"names":[],"mappings":"AAmCA;;;GAGG;AACH,MAAM,UAAU,OAAO,CAA0B,KAAqB;IACpE,6HAA6H;IAC7H,OAAO,KAAe,CAAA;AACxB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guillaume-docquier/tools-ts",
-  "version": "7.5.2",
+  "version": "8.0.0",
   "description": "My personal collection of typescript tools",
   "homepage": "https://github.com/Guillaume-Docquier/tools-ts",
   "license": "MIT",
@@ -25,30 +25,29 @@
     "provenance": true
   },
   "dependencies": {
-    "@logtape/logtape": "^2.3.2",
-    "@logtape/redaction": "^2.3.2"
+    "@logtape/logtape": "^2.3.3",
+    "@logtape/redaction": "^2.3.3"
   },
   "devDependencies": {
-    "@guillaume-docquier/oxfmt": "^1.0.6",
-    "@guillaume-docquier/oxlint": "^1.8.0",
+    "@guillaume-docquier/oxfmt": "^1.0.8",
+    "@guillaume-docquier/oxlint": "^1.8.1",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/github": "^12.0.9",
     "@semantic-release/release-notes-generator": "^14.1.1",
-    "@types/node": "^25.9.5",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "^5.0.0",
     "conventional-changelog-conventionalcommits": "^9.3.1",
     "husky": "^9.1.7",
     "jiti": "^2.7.0",
-    "lint-staged": "^16.4.0",
-    "oxfmt": "^0.65.0",
-    "oxlint": "^1.80.0",
+    "lint-staged": "^17.5.0",
+    "oxfmt": ">=0.67.0",
+    "oxlint": "^1.82.0",
     "oxlint-tsgolint": "^7.0.2001",
     "semantic-release": "^25.0.9",
     "typescript": "~7.0.2",
     "vite": "^8.2.2",
-    "vitest": "^4.1.11",
-    "node": "runtime:26.8.1"
+    "vitest": "^5.0.0"
   },
   "lint-staged": {
     "*.{md,json,yml,yaml,css,scss}": "oxfmt --no-error-on-unmatched-pattern",
@@ -60,7 +59,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "11.24.0",
+      "version": "12.3.4",
       "onFail": "download"
     },
     "runtime": {