@everystack/model 0.3.4 → 0.3.6

package/README.md

@@ -72,7 +72,9 @@ 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.
 
 `.validate(...)` does double duty: the SQL-expressible refinements (`min`/`max`/`length`/range/enum) become a Postgres `CHECK` — the backstop for the SSR-direct write path that never runs app-layer Zod — while richer refinements stay app-layer only.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.3.4",
+  "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

package/src/model.ts

@@ -63,6 +63,15 @@ export interface ModelDefinition {
    * can span schemas — the model's schema always wins over a generate call's default.
    */
   schema?: string;
+  /**
+   * `renamedFrom: 'old_table'` — a one-shot migration hint, the table-level
+   * analog of `field.renamedFrom()`. A diff cannot distinguish RENAME from
+   * DROP+ADD; the marker carries the intent, so the diff emits one
+   * `ALTER TABLE … RENAME TO …` (data preserved) instead of CREATE plus a
+   * held DROP. Same schema as the model. Remove it once every environment
+   * is past the state — a satisfied rename is an inert notice.
+   */
+  renamedFrom?: string;
   /**
    * `true` removes the table from the generic data API — `deriveHandlerConfig`
    * skips it, so it never enters `exposedTables`. Default `false`. Package-owned
@@ -90,6 +99,8 @@ export interface ModelDescriptor {
   schema: string;
   /** `true` removes the table from the generic data API (not in `exposedTables`). Default `false`. */
   private: boolean;
+  /** One-shot rename hint: this table used to be named `renamedFrom` (same schema). */
+  renamedFrom?: string;
 }
 
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
@@ -108,5 +119,6 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     writtenBy: def.writtenBy ?? 'app',
     schema: def.schema ?? 'public',
     private: def.private ?? false,
+    ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),
   };
 }