@everystack/model 0.3.5 → 0.3.6

package/README.md

@@ -72,7 +72,7 @@ export const models = [Account, Note];
 | `field.jsonb()` | `jsonb` |
 | `field.enum('name', [...])` | a `CREATE TYPE … AS ENUM` (name is explicit, so `db:pull` round-trips it) |
 
-Modifiers: `.primaryKey()`, `.notNull()` / `.nullable()`, `.unique()`, `.default(value)` / `.defaultNow()` / `.defaultRandom()`, `.references(() => Other, { onDelete, onUpdate })`, `.private()` (never serialized), `.readonly()` (never accepted on write), `.validate(zodSchema)`, and `.renamedFrom('oldField')` (turns a drop+add into a data-preserving `RENAME COLUMN`).
+Modifiers: `.primaryKey()`, `.notNull()` / `.nullable()`, `.unique()`, `.default(value)` / `.defaultNow()` / `.defaultRandom()`, `.references(() => Other, { onDelete, onUpdate })`, `.private()` (never serialized), `.readonly()` (never accepted on write), `.validate(zodSchema)`, `.renamedFrom('oldField')` (turns a drop+add into a data-preserving `RENAME COLUMN`), and `.deprecated()` (the contract phase of contraction: the column stays in the database and stays readable — old clients keep working — while new writes are rejected and generated types strike it through; deleting the field later is the actual drop, destructive and gated).
 
 Renaming a whole table works the same way, at the model level: `defineModel('articles', { renamedFrom: 'posts', ... })` compiles to one `ALTER TABLE … RENAME TO …` (data preserved, policies ride along) instead of CREATE plus a held DROP. Both markers are one-shot — remove them once every environment is past the state; a satisfied rename is an inert notice.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/derive.ts

@@ -66,8 +66,10 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
     const privateCols = fieldsWhere(model, (f) => f.spec.isPrivate);
     if (privateCols.length) hiddenColumns[table] = privateCols;
 
-    // .readonly() → protectedFields (mass-assignment guard).
-    const readonlyCols = fieldsWhere(model, (f) => f.spec.isReadonly);
+    // .readonly() → protectedFields (mass-assignment guard). A deprecated field
+    // joins it — the contract phase rejects new writes but keeps reads serving
+    // (stale clients read for weeks; hiding it would break them before the drop).
+    const readonlyCols = fieldsWhere(model, (f) => f.spec.isReadonly || f.spec.isDeprecated);
     if (readonlyCols.length) protectedFields[table] = readonlyCols;
 
     // The first owner-shaped ability → the handler's rowOwnership IDOR backstop.

package/src/field.ts

@@ -55,6 +55,14 @@ export interface FieldSpec {
   isPrivate: boolean;
   /** `.readonly()` — never accepted on write (→ `protectedFields`). */
   isReadonly: boolean;
+  /**
+   * `.deprecated()` — the contract phase of contraction. The column stays in the
+   * database and stays READABLE (stale clients keep working); it leaves the write
+   * surface (→ `protectedFields`) and is struck through in generated types
+   * (`@deprecated` in the drizzle schema). Deleting the field from the model is
+   * the physical drop — a destructive, role-gated act.
+   */
+  isDeprecated: boolean;
   /** `.references(() => Other)` — FK target, a model thunk. Used by relation/ownership work. */
   references?: () => unknown;
   /** `ON DELETE` action for the FK. Omitted (or `'no action'`) is the Postgres default. */
@@ -97,6 +105,7 @@ export class FieldBuilder {
       isArray: false,
       isPrivate: false,
       isReadonly: false,
+      isDeprecated: false,
     };
   }
 
@@ -139,6 +148,18 @@ export class FieldBuilder {
     return this;
   }
 
+  /**
+   * Mark the contract phase of contraction (expand → deprecate → drop). The column
+   * stays in the database and stays readable — old clients keep working — but new
+   * writes are rejected (`protectedFields`) and generated types strike it through.
+   * The physical drop is deleting the field from the model: a destructive plan,
+   * confirmed, snapshotted, and approver-gated on protected stages.
+   */
+  deprecated(): this {
+    this.spec.isDeprecated = true;
+    return this;
+  }
+
   /**
    * Declare a foreign key. The target is a model thunk (forward-reference safe). Optional
    * `onDelete`/`onUpdate` referential actions are column-scoped, so they live here, not on