@everystack/model 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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/index.ts

@@ -22,8 +22,8 @@ export type { Ability, AbilityCondition, Action } from './can';
 export { belongsTo, hasMany } from './relations';
 export type { Relation } from './relations';
 
-export { defineModel } from './model';
-export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy } from './model';
+export { defineModel, defineMaterializedTable } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
 export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived } from './module';
 export type { Module, ModuleDefinition } from './module';

package/src/model.ts

@@ -15,7 +15,8 @@ import type { FieldBuilder } from './field';
 import type { Ability } from './can';
 import type { Relation } from './relations';
 import type { TableConstraint } from './constraints';
-import { validateTriggersFor, type TriggerSpec } from './derived';
+import type { RawSql } from './raw-sql';
+import { validateTriggersFor, type TriggerSpec, type DependsOnRef } from './derived';
 
 /**
  * Per-table mutation hooks. Imperative function bodies the framework cannot
@@ -112,6 +113,24 @@ export interface ModelDescriptor {
   renamedFrom?: string;
   /** Triggers on this table (compute — reconciled, never migrated; excluded from the base fingerprint). */
   triggers: TriggerSpec[];
+  /**
+   * Set by {@link defineMaterializedTable}: this table is a materialized cache — served as a
+   * TABLE (migrated, fingerprinted, authz'd like any table), but its CONTENTS are pipeline-owned.
+   * everystack NEVER reconciles or refreshes it; the declared query and deps are metadata for the
+   * pipeline, codegen, and build ordering. Excluded from the base fingerprint (the query is not a
+   * database fact — only the columns are), so it hashes identically to the equivalent plain table.
+   */
+  materialized?: MaterializedTableMarker;
+}
+
+/** The declared-query metadata a {@link defineMaterializedTable} carries — never executed by everystack. */
+export interface MaterializedTableMarker {
+  /** The defining query (deparsed from `sql\`\``). The pipeline computes the contents FROM it;
+   *  everystack keeps it for round-trip, codegen, and build ordering — it does not run it. */
+  as: string;
+  /** Objects this table's contents are computed from — build-order edges for the pipeline. */
+  dependsOn: DependsOnRef[];
+  comment?: string;
 }
 
 export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
@@ -157,3 +176,56 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     triggers: def.triggers ?? [],
   };
 }
+
+/**
+ * A MATERIALIZED TABLE — a matview that is shipped and served as a plain table. A refresh-free
+ * hot-swap (docs/plans/canonical-sync-artifacts.md) cannot populate a materialized VIEW without
+ * REFRESH, so a canonical dataset that must serve exact, pre-computed bytes lives in a table. This
+ * declares that table: real columns (fingerprinted, migrated, authz'd like any table, FK-targetable
+ * by other schemas), plus the defining query as METADATA. everystack never runs, reconciles, or
+ * refreshes it — the pipeline computes the contents locally and ships them in the artifact. The
+ * query and deps round-trip through codegen and drive the pipeline's build order.
+ *
+ * Contrast: {@link defineMaterializedView} is COMPUTE (reconciled + refreshed by everystack);
+ * this is STATE (a table everystack migrates, whose data an external pipeline owns).
+ */
+export interface MaterializedTableDefinition {
+  fields: Record<string, FieldBuilder>;
+  abilities?: Ability[];
+  schema?: string;
+  constraints?: TableConstraint[];
+  /** Build-order edges — the objects the pipeline computes this table's contents FROM. */
+  dependsOn?: DependsOnRef[];
+  /** The defining query. everystack keeps it (round-trip, codegen, ordering) but NEVER runs it. */
+  as: RawSql;
+  comment?: string;
+  /** Write principal — default `'worker'` (the pipeline loads it on the owner connection,
+   *  bypassing RLS), so RLS is ENABLE-not-FORCE, matching how the swap loads the rows. */
+  writtenBy?: WrittenBy;
+  private?: boolean;
+  renamedFrom?: string;
+}
+
+export function defineMaterializedTable(table: string, def: MaterializedTableDefinition): ModelDescriptor {
+  if (def.as == null) {
+    throw new Error(`materialized table '${table}': as (the defining query) is ${def.as === undefined ? 'undefined' : 'null'} — declare as: sql\`SELECT …\`.`);
+  }
+  for (const [i, d] of (def.dependsOn ?? []).entries()) {
+    if (d == null) throw new Error(`materialized table '${table}': dependsOn[${i}] is ${d === undefined ? 'undefined' : 'null'} — renamed or missing import?`);
+  }
+  const model = defineModel(table, {
+    fields: def.fields,
+    abilities: def.abilities,
+    schema: def.schema,
+    constraints: def.constraints,
+    writtenBy: def.writtenBy ?? 'worker',
+    private: def.private,
+    ...(def.renamedFrom ? { renamedFrom: def.renamedFrom } : {}),
+  });
+  model.materialized = {
+    as: def.as.sql,
+    dependsOn: def.dependsOn ?? [],
+    ...(def.comment ? { comment: def.comment } : {}),
+  };
+  return model;
+}