rastack 0.0.16 → 0.0.20

package/sync/types.ts

@@ -1,94 +1,94 @@
-export type EntityKey = string; // `${app}.${model}`
-
-export interface EntityDescriptor<TRow = any> {
-  app: string;
-  model: string;
-  /** Collection endpoint, e.g. /api/shop/v1/pets */
-  listUrl: string;
-  /** Detail endpoint builder, e.g. (id) => `/api/shop/v1/pets/${id}` */
-  detailUrl?: (id: string) => string;
-  /** Primary key field on the row. Defaults to "id". */
-  idField?: string;
-  /**
-   * Lazy entities (Sync.load = "lazy") are excluded from the initial
-   * bootstrap and partial-bootstrapped on first use instead.
-   */
-  lazy?: boolean;
-  /**
-   * Sync.client_ids = True: the row's primary key is a client-generated
-   * UUID, so creates carry their real id from the start (no temp-id
-   * reconciliation) and offline-created rows can be referenced immediately.
-   */
-  clientIds?: boolean;
-  /** Phantom field so TRow is used; never set at runtime. */
-  __row?: TRow;
-}
-
-export function entityKey(entity: EntityDescriptor): EntityKey {
-  return `${entity.app}.${entity.model}`;
-}
-
-export type SyncOp = "I" | "U" | "D";
-
-export interface SyncActionPacket {
-  op: SyncOp;
-  model: EntityKey;
-  id: string;
-  data: Record<string, any> | null;
-  sync_id: number;
-}
-
-export interface ChangesResponse {
-  actions: SyncActionPacket[];
-  last_sync_id: number;
-  /** Hash of the sync-relevant server schema; a change forces a re-bootstrap. */
-  schema_hash?: string;
-}
-
-export interface BootstrapResponse {
-  models: { [key: EntityKey]: Record<string, any>[] };
-  last_sync_id: number;
-  schema_hash?: string;
-}
-
-export type TransactionOp = "create" | "update" | "delete";
-
-export type TransactionStatus = "queued" | "inflight" | "completed";
-
-export interface SyncTransaction {
-  txnId: string;
-  entity: EntityKey;
-  op: TransactionOp;
-  /** Row id. Creates use a temporary `tmp_*` id until the server echoes the real one. */
-  id: string;
-  method: "post" | "put" | "patch" | "delete";
-  url: string;
-  payload: Record<string, any> | null;
-  /**
-   * Rollback snapshot: for updates, the previous values of the changed
-   * fields; for deletes, the full previous row; null for creates.
-   */
-  original: Record<string, any> | null;
-  status: TransactionStatus;
-  createdAt: number;
-}
-
-export type EngineStatus =
-  | "idle"
-  | "hydrating"
-  | "bootstrapping"
-  | "live"
-  | "offline"
-  | "error";
-
-export interface SyncEngineConfig {
-  /** Base path of the sync endpoints. */
-  syncBasePath?: string; // default /api/sync/v1
-  /** Long-poll hold time requested from /changes, seconds. */
-  wait?: number; // default 25
-  /** Persist to IndexedDB (default true; falls back to memory when unavailable). */
-  persist?: boolean;
-  /** Database name for IndexedDB. */
-  databaseName?: string; // default "rad-sync"
-  onError?: (error: unknown) => void;
-}
+export type EntityKey = string; // `${app}.${model}`
+
+export interface EntityDescriptor<TRow = any> {
+  app: string;
+  model: string;
+  /** Collection endpoint, e.g. /api/shop/v1/pets */
+  listUrl: string;
+  /** Detail endpoint builder, e.g. (id) => `/api/shop/v1/pets/${id}` */
+  detailUrl?: (id: string) => string;
+  /** Primary key field on the row. Defaults to "id". */
+  idField?: string;
+  /**
+   * Lazy entities (Sync.load = "lazy") are excluded from the initial
+   * bootstrap and partial-bootstrapped on first use instead.
+   */
+  lazy?: boolean;
+  /**
+   * Sync.client_ids = True: the row's primary key is a client-generated
+   * UUID, so creates carry their real id from the start (no temp-id
+   * reconciliation) and offline-created rows can be referenced immediately.
+   */
+  clientIds?: boolean;
+  /** Phantom field so TRow is used; never set at runtime. */
+  __row?: TRow;
+}
+
+export function entityKey(entity: EntityDescriptor): EntityKey {
+  return `${entity.app}.${entity.model}`;
+}
+
+export type SyncOp = "I" | "U" | "D";
+
+export interface SyncActionPacket {
+  op: SyncOp;
+  model: EntityKey;
+  id: string;
+  data: Record<string, any> | null;
+  sync_id: number;
+}
+
+export interface ChangesResponse {
+  actions: SyncActionPacket[];
+  last_sync_id: number;
+  /** Hash of the sync-relevant server schema; a change forces a re-bootstrap. */
+  schema_hash?: string;
+}
+
+export interface BootstrapResponse {
+  models: { [key: EntityKey]: Record<string, any>[] };
+  last_sync_id: number;
+  schema_hash?: string;
+}
+
+export type TransactionOp = "create" | "update" | "delete";
+
+export type TransactionStatus = "queued" | "inflight" | "completed";
+
+export interface SyncTransaction {
+  txnId: string;
+  entity: EntityKey;
+  op: TransactionOp;
+  /** Row id. Creates use a temporary `tmp_*` id until the server echoes the real one. */
+  id: string;
+  method: "post" | "put" | "patch" | "delete";
+  url: string;
+  payload: Record<string, any> | null;
+  /**
+   * Rollback snapshot: for updates, the previous values of the changed
+   * fields; for deletes, the full previous row; null for creates.
+   */
+  original: Record<string, any> | null;
+  status: TransactionStatus;
+  createdAt: number;
+}
+
+export type EngineStatus =
+  | "idle"
+  | "hydrating"
+  | "bootstrapping"
+  | "live"
+  | "offline"
+  | "error";
+
+export interface SyncEngineConfig {
+  /** Base path of the sync endpoints. */
+  syncBasePath?: string; // default /api/sync/v1
+  /** Long-poll hold time requested from /changes, seconds. */
+  wait?: number; // default 25
+  /** Persist to IndexedDB (default true; falls back to memory when unavailable). */
+  persist?: boolean;
+  /** Database name for IndexedDB. */
+  databaseName?: string; // default "rad-sync"
+  onError?: (error: unknown) => void;
+}

package/test/compile.spec.ts

@@ -1,192 +1,192 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
-import { join } from "path";
-import {
-  analyzeResources,
-  buildOpenApi,
-  collisions,
-  compile,
-  ResourceModel,
-} from "../src/compile";
-import { generateFiles, generateFolders } from "../src/schema-entities";
-import { removeNonModelPaths } from "../src/schema/remove-non-model-paths";
-
-/**
- * The compiler's fixtures are real `.ts` files that import the DSL by its
- * package name (`rad-tools/define`); `createProgram` maps that to the in-tree
- * source, so the type checker resolves the `Ref`/`Resource` brands exactly as it
- * would in a consumer project.
- */
-const workRoot = join(__dirname, "compile-fixtures");
-const resourcesDir = join(workRoot, "resources");
-const outDir = join(workRoot, "out");
-
-const AIRPORTS_TS = `
-import { resource, s } from "rad-tools/define";
-
-export const Airport = resource("airports", "airport", {
-  code: s.string({ maxLength: 3, unique: true }),
-  name: s.string({ maxLength: 120 }),
-}, { search: ["code", "name"], admin: { listDisplay: ["code", "name"] } });
-
-export const Terminal = resource("airports", "terminal", {
-  airport: s.ref(() => Airport),
-  label: s.string({ maxLength: 20 }),
-});
-
-export const Flight = resource("airports", "flight", {
-  number: s.string({ maxLength: 8 }),
-  status: s.string({ maxLength: 20, default: "scheduled" }),
-}, { sync: { mode: "local", scope: "owner_id={user.id}", confirmed: ["update"] } });
-
-export const Gate = resource("airports", "gate", {
-  number: s.string({ maxLength: 5 }),
-}, { sync: { mode: "local", load: "lazy" } });
-
-export const Booking = resource("airports", "booking", {
-  reference: s.string({ maxLength: 12 }),
-}, { sync: { mode: "local", clientIds: true } });
-`;
-
-function findResource(
-  resources: ResourceModel[],
-  app: string,
-  model: string,
-): ResourceModel {
-  const found = resources.find((r) => r.app === app && r.model === model);
-  if (!found) throw new Error(`missing ${app}.${model}`);
-  return found;
-}
-
-describe("rad compile — resource analysis & FK inference", () => {
-  beforeAll(() => {
-    mkdirSync(resourcesDir, { recursive: true });
-    writeFileSync(join(resourcesDir, "airports.ts"), AIRPORTS_TS);
-  });
-
-  afterAll(() => {
-    rmSync(workRoot, { recursive: true, force: true });
-  });
-
-  it("infers a foreign key from the field type", () => {
-    const resources = analyzeResources(resourcesDir);
-    const terminal = findResource(resources, "airports", "terminal");
-
-    const airportField = terminal.fields.find((f) => f.name === "airport");
-    expect(airportField?.type).toBe("fk");
-    expect(airportField?.relation).toEqual({ app: "airports", model: "airport" });
-
-    expect(terminal.relations).toEqual([
-      { field: "airport", target: "airports.airport", kind: "fk" },
-    ]);
-  });
-
-  it("maps scalar fields and their constraints", () => {
-    const resources = analyzeResources(resourcesDir);
-    const airport = findResource(resources, "airports", "airport");
-
-    const code = airport.fields.find((f) => f.name === "code");
-    expect(code).toMatchObject({ type: "string", maxLength: 3, unique: true });
-
-    const name = airport.fields.find((f) => f.name === "name");
-    expect(name).toMatchObject({ type: "string", maxLength: 120 });
-
-    expect(airport.search).toEqual(["code", "name"]);
-    expect(airport.admin).toEqual({ listDisplay: ["code", "name"] });
-  });
-
-  it("captures sync config (local / lazy / client-ids / confirmed)", () => {
-    const resources = analyzeResources(resourcesDir);
-
-    expect(findResource(resources, "airports", "flight").sync).toMatchObject({
-      mode: "local",
-      scope: "owner_id={user.id}",
-      confirmed: ["update"],
-    });
-    expect(findResource(resources, "airports", "gate").sync).toMatchObject({
-      mode: "local",
-      load: "lazy",
-    });
-    expect(findResource(resources, "airports", "booking").sync).toMatchObject({
-      mode: "local",
-      clientIds: true,
-    });
-  });
-
-  it("reports no collisions for a valid graph", () => {
-    const resources = analyzeResources(resourcesDir);
-    expect(collisions(resources)).toEqual([]);
-  });
-});
-
-describe("rad compile — OpenAPI emission", () => {
-  beforeAll(() => {
-    mkdirSync(resourcesDir, { recursive: true });
-    writeFileSync(join(resourcesDir, "airports.ts"), AIRPORTS_TS);
-  });
-
-  afterAll(() => {
-    rmSync(workRoot, { recursive: true, force: true });
-  });
-
-  it("writes schema.rad.json and openapi.json", () => {
-    const result = compile(resourcesDir, outDir);
-    expect(existsSync(join(outDir, "schema.rad.json"))).toBe(true);
-    expect(existsSync(join(outDir, "openapi.json"))).toBe(true);
-    expect(result.manifest.resources.length).toBe(5);
-  });
-
-  it("emits the /api/{app}/v1/{model}/ contract with FK + sync extensions", () => {
-    const resources = analyzeResources(resourcesDir);
-    const doc = buildOpenApi(resources);
-
-    // URL-segment contract the codegen keys off.
-    expect(doc.paths["/api/airports/v1/terminal/"]).toBeDefined();
-    expect(doc.paths["/api/airports/v1/terminal/{id}/"]).toBeDefined();
-
-    // FK field carries the new relation extension.
-    const terminalSchema = doc.components.schemas.Terminal;
-    expect(terminalSchema.properties.airport["x-rastack-relation"]).toEqual({
-      app: "airports",
-      model: "airport",
-    });
-
-    // Local-mode sync extensions, confirmed on update.
-    const flightList = doc.paths["/api/airports/v1/flight/"];
-    expect(flightList.get["x-rastack-sync"]).toBe("local");
-    expect(doc.paths["/api/airports/v1/flight/{id}/"].put["x-rastack-sync"]).toBe(
-      "confirmed",
-    );
-    expect(doc.paths["/api/airports/v1/gate/"].get["x-rastack-sync-load"]).toBe(
-      "lazy",
-    );
-    expect(
-      doc.paths["/api/airports/v1/booking/"].post["x-rastack-sync-client-ids"],
-    ).toBe(true);
-  });
-
-  it("round-trips through the existing hooks codegen", async () => {
-    const resources = analyzeResources(resourcesDir);
-    const doc = buildOpenApi(resources);
-    const paths = removeNonModelPaths(doc.paths);
-
-    const entitiesPath = join(workRoot, "entities");
-    mkdirSync(entitiesPath, { recursive: true });
-    await generateFolders(entitiesPath, paths);
-    await generateFiles(entitiesPath, paths);
-
-    // Non-sync entity → plain async hook.
-    const airportApi = readFileSync(
-      join(entitiesPath, "airports", "airport", "api.ts"),
-      "utf-8",
-    );
-    expect(airportApi).toContain("export function useListAirport(");
-
-    // Sync entity → store-backed hooks + a defineEntity descriptor.
-    const flightApi = readFileSync(
-      join(entitiesPath, "airports", "flight", "api.ts"),
-      "utf-8",
-    );
-    expect(flightApi).toContain("defineEntity<IFlight>({");
-    expect(flightApi).toContain("from 'rastack/sync'");
-  });
-});
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import {
+  analyzeResources,
+  buildOpenApi,
+  collisions,
+  compile,
+  ResourceModel,
+} from "../src/compile";
+import { generateFiles, generateFolders } from "../src/schema-entities";
+import { removeNonModelPaths } from "../src/schema/remove-non-model-paths";
+
+/**
+ * The compiler's fixtures are real `.ts` files that import the DSL by its
+ * package name (`rad-tools/define`); `createProgram` maps that to the in-tree
+ * source, so the type checker resolves the `Ref`/`Resource` brands exactly as it
+ * would in a consumer project.
+ */
+const workRoot = join(__dirname, "compile-fixtures");
+const resourcesDir = join(workRoot, "resources");
+const outDir = join(workRoot, "out");
+
+const AIRPORTS_TS = `
+import { resource, s } from "rad-tools/define";
+
+export const Airport = resource("airports", "airport", {
+  code: s.string({ maxLength: 3, unique: true }),
+  name: s.string({ maxLength: 120 }),
+}, { search: ["code", "name"], admin: { listDisplay: ["code", "name"] } });
+
+export const Terminal = resource("airports", "terminal", {
+  airport: s.ref(() => Airport),
+  label: s.string({ maxLength: 20 }),
+});
+
+export const Flight = resource("airports", "flight", {
+  number: s.string({ maxLength: 8 }),
+  status: s.string({ maxLength: 20, default: "scheduled" }),
+}, { sync: { mode: "local", scope: "owner_id={user.id}", confirmed: ["update"] } });
+
+export const Gate = resource("airports", "gate", {
+  number: s.string({ maxLength: 5 }),
+}, { sync: { mode: "local", load: "lazy" } });
+
+export const Booking = resource("airports", "booking", {
+  reference: s.string({ maxLength: 12 }),
+}, { sync: { mode: "local", clientIds: true } });
+`;
+
+function findResource(
+  resources: ResourceModel[],
+  app: string,
+  model: string,
+): ResourceModel {
+  const found = resources.find((r) => r.app === app && r.model === model);
+  if (!found) throw new Error(`missing ${app}.${model}`);
+  return found;
+}
+
+describe("rad compile — resource analysis & FK inference", () => {
+  beforeAll(() => {
+    mkdirSync(resourcesDir, { recursive: true });
+    writeFileSync(join(resourcesDir, "airports.ts"), AIRPORTS_TS);
+  });
+
+  afterAll(() => {
+    rmSync(workRoot, { recursive: true, force: true });
+  });
+
+  it("infers a foreign key from the field type", () => {
+    const resources = analyzeResources(resourcesDir);
+    const terminal = findResource(resources, "airports", "terminal");
+
+    const airportField = terminal.fields.find((f) => f.name === "airport");
+    expect(airportField?.type).toBe("fk");
+    expect(airportField?.relation).toEqual({ app: "airports", model: "airport" });
+
+    expect(terminal.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+  });
+
+  it("maps scalar fields and their constraints", () => {
+    const resources = analyzeResources(resourcesDir);
+    const airport = findResource(resources, "airports", "airport");
+
+    const code = airport.fields.find((f) => f.name === "code");
+    expect(code).toMatchObject({ type: "string", maxLength: 3, unique: true });
+
+    const name = airport.fields.find((f) => f.name === "name");
+    expect(name).toMatchObject({ type: "string", maxLength: 120 });
+
+    expect(airport.search).toEqual(["code", "name"]);
+    expect(airport.admin).toEqual({ listDisplay: ["code", "name"] });
+  });
+
+  it("captures sync config (local / lazy / client-ids / confirmed)", () => {
+    const resources = analyzeResources(resourcesDir);
+
+    expect(findResource(resources, "airports", "flight").sync).toMatchObject({
+      mode: "local",
+      scope: "owner_id={user.id}",
+      confirmed: ["update"],
+    });
+    expect(findResource(resources, "airports", "gate").sync).toMatchObject({
+      mode: "local",
+      load: "lazy",
+    });
+    expect(findResource(resources, "airports", "booking").sync).toMatchObject({
+      mode: "local",
+      clientIds: true,
+    });
+  });
+
+  it("reports no collisions for a valid graph", () => {
+    const resources = analyzeResources(resourcesDir);
+    expect(collisions(resources)).toEqual([]);
+  });
+});
+
+describe("rad compile — OpenAPI emission", () => {
+  beforeAll(() => {
+    mkdirSync(resourcesDir, { recursive: true });
+    writeFileSync(join(resourcesDir, "airports.ts"), AIRPORTS_TS);
+  });
+
+  afterAll(() => {
+    rmSync(workRoot, { recursive: true, force: true });
+  });
+
+  it("writes schema.rad.json and openapi.json", () => {
+    const result = compile(resourcesDir, outDir);
+    expect(existsSync(join(outDir, "schema.rad.json"))).toBe(true);
+    expect(existsSync(join(outDir, "openapi.json"))).toBe(true);
+    expect(result.manifest.resources.length).toBe(5);
+  });
+
+  it("emits the /api/{app}/v1/{model}/ contract with FK + sync extensions", () => {
+    const resources = analyzeResources(resourcesDir);
+    const doc = buildOpenApi(resources);
+
+    // URL-segment contract the codegen keys off.
+    expect(doc.paths["/api/airports/v1/terminal/"]).toBeDefined();
+    expect(doc.paths["/api/airports/v1/terminal/{id}/"]).toBeDefined();
+
+    // FK field carries the new relation extension.
+    const terminalSchema = doc.components.schemas.Terminal;
+    expect(terminalSchema.properties.airport["x-rastack-relation"]).toEqual({
+      app: "airports",
+      model: "airport",
+    });
+
+    // Local-mode sync extensions, confirmed on update.
+    const flightList = doc.paths["/api/airports/v1/flight/"];
+    expect(flightList.get["x-rastack-sync"]).toBe("local");
+    expect(doc.paths["/api/airports/v1/flight/{id}/"].put["x-rastack-sync"]).toBe(
+      "confirmed",
+    );
+    expect(doc.paths["/api/airports/v1/gate/"].get["x-rastack-sync-load"]).toBe(
+      "lazy",
+    );
+    expect(
+      doc.paths["/api/airports/v1/booking/"].post["x-rastack-sync-client-ids"],
+    ).toBe(true);
+  });
+
+  it("round-trips through the existing hooks codegen", async () => {
+    const resources = analyzeResources(resourcesDir);
+    const doc = buildOpenApi(resources);
+    const paths = removeNonModelPaths(doc.paths);
+
+    const entitiesPath = join(workRoot, "entities");
+    mkdirSync(entitiesPath, { recursive: true });
+    await generateFolders(entitiesPath, paths);
+    await generateFiles(entitiesPath, paths);
+
+    // Non-sync entity → plain async hook.
+    const airportApi = readFileSync(
+      join(entitiesPath, "airports", "airport", "api.ts"),
+      "utf-8",
+    );
+    expect(airportApi).toContain("export function useListAirport(");
+
+    // Sync entity → store-backed hooks + a defineEntity descriptor.
+    const flightApi = readFileSync(
+      join(entitiesPath, "airports", "flight", "api.ts"),
+      "utf-8",
+    );
+    expect(flightApi).toContain("defineEntity<IFlight>({");
+    expect(flightApi).toContain("from 'rastack/sync'");
+  });
+});