@warlock.js/cascade 4.2.11 → 4.4.0

package/CHANGELOG.md

@@ -4,7 +4,11 @@ All notable changes to `@warlock.js/cascade` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
-## [Unreleased]
+## 4.4.0 - 2026-06-21
+
+### Changed
+
+- **Documented `model.uuid`** — clarified that the accessor returns the model's primary id as `string` (where `model.id` is `string | number`); the name is historical and performs no UUID validation or coercion.
 
 ## 4.2.11
 

package/llms-full.txt

@@ -925,16 +925,35 @@ export class User extends Model<UserSchema> {
 - `static table` matches the migration. Plural, lowercase, snake_case is the convention on both drivers.
 - `static schema` attaches the validator. On every `save()`, the data goes through `userSchema` before it hits the database.
 
-## Read state — `.id` and `.get(field)`
+## Read state — `.id`, `.uuid`, and `.get(field)`
 
 ```ts
 user.id;                   // direct property — ID is so common cascade exposes it directly
+user.uuid;                 // the same id, narrowed to `string` (see below)
 user.get("status");        // canonical reader for every other column
 user.get<number>("age");   // TypeScript generic for typed reads
 ```
 
 Use the direct `.id` property; use `.get("field")` for everything else. Add a typed getter on the model class when the same field is read in many places — turns N typed-cast call sites into one named accessor.
 
+### `.id` vs `.uuid` — a TypeScript convenience, same value
+
+Both getters return the model's primary id (`this.get("id")`); the only difference is the **static type**:
+
+| Accessor | Return type | Use when |
+|---|---|---|
+| `model.id` | `string \| number` | You want the real id type — SQL auto-increment is `number`, MongoDB's ObjectId is `string`. |
+| `model.uuid` | `string` | You want to pass the id to code typed for a single `string` id, without leaking the engine's `string \| number` union everywhere. |
+
+`uuid` does **not** validate or coerce the value to a UUID — the name is historical. It simply returns the same id, typed as `string`, so a helper typed for a string id accepts it on either engine:
+
+```ts
+function shareLink(modelId: string) { /* ... */ }
+
+shareLink(user.uuid);  // ✓ typechecks on both Postgres and MongoDB
+shareLink(user.id);    // ✗ TS error on SQL: `number` is not assignable to `string`
+```
+
 ## Write — three update idioms
 
 Cascade gives you three ways to update an instance. Knowing when each fits saves you from reaching for the wrong one.

package/package.json

@@ -27,9 +27,9 @@
     "@mongez/events": "^2.2.6",
     "@mongez/reinforcements": "^3.3.0",
     "@mongez/supportive-is": "^2.1.3",
-    "@warlock.js/context": "4.2.11",
-    "@warlock.js/logger": "4.2.11",
-    "@warlock.js/seal": "4.2.11",
+    "@warlock.js/context": "4.4.0",
+    "@warlock.js/logger": "4.4.0",
+    "@warlock.js/seal": "4.4.0",
     "citty": "^0.2.2",
     "fast-glob": "^3.3.3"
   },
@@ -40,7 +40,7 @@
   "bin": {
     "cascade": "bin/cascade.js"
   },
-  "version": "4.2.11",
+  "version": "4.4.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/define-model/SKILL.md

@@ -45,16 +45,35 @@ export class User extends Model<UserSchema> {
 - `static table` matches the migration. Plural, lowercase, snake_case is the convention on both drivers.
 - `static schema` attaches the validator. On every `save()`, the data goes through `userSchema` before it hits the database.
 
-## Read state — `.id` and `.get(field)`
+## Read state — `.id`, `.uuid`, and `.get(field)`
 
 ```ts
 user.id;                   // direct property — ID is so common cascade exposes it directly
+user.uuid;                 // the same id, narrowed to `string` (see below)
 user.get("status");        // canonical reader for every other column
 user.get<number>("age");   // TypeScript generic for typed reads
 ```
 
 Use the direct `.id` property; use `.get("field")` for everything else. Add a typed getter on the model class when the same field is read in many places — turns N typed-cast call sites into one named accessor.
 
+### `.id` vs `.uuid` — a TypeScript convenience, same value
+
+Both getters return the model's primary id (`this.get("id")`); the only difference is the **static type**:
+
+| Accessor | Return type | Use when |
+|---|---|---|
+| `model.id` | `string \| number` | You want the real id type — SQL auto-increment is `number`, MongoDB's ObjectId is `string`. |
+| `model.uuid` | `string` | You want to pass the id to code typed for a single `string` id, without leaking the engine's `string \| number` union everywhere. |
+
+`uuid` does **not** validate or coerce the value to a UUID — the name is historical. It simply returns the same id, typed as `string`, so a helper typed for a string id accepts it on either engine:
+
+```ts
+function shareLink(modelId: string) { /* ... */ }
+
+shareLink(user.uuid);  // ✓ typechecks on both Postgres and MongoDB
+shareLink(user.id);    // ✗ TS error on SQL: `number` is not assignable to `string`
+```
+
 ## Write — three update idioms
 
 Cascade gives you three ways to update an instance. Knowing when each fits saves you from reaching for the wrong one.