@jskit-ai/crud-server-generator 0.1.26 → 0.1.28

package/test/addFieldSubcommand.test.js

@@ -0,0 +1,167 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { runGeneratorSubcommand } from "../src/server/subcommands/addField.js";
+
+const RESOURCE_SOURCE = `import { Type } from "typebox";
+import { normalizeObjectInput, createCursorListValidator } from "@jskit-ai/kernel/shared/validators";
+import { normalizeText, normalizeIfInSource, normalizeIfPresent, normalizeOrNull } from "@jskit-ai/kernel/shared/support/normalize";
+
+const RESOURCE_LOOKUP_CONTAINER_KEY = "lookups";
+
+const recordOutputSchema = Type.Object(
+  {
+    id: Type.Integer({ minimum: 1 }),
+    firstName: Type.Union([Type.String(), Type.Null()]),
+    [RESOURCE_LOOKUP_CONTAINER_KEY]: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
+  },
+  { additionalProperties: false }
+);
+
+const createBodySchema = Type.Object(
+  {
+    firstName: Type.Union([Type.String({ maxLength: 160 }), Type.Null()])
+  },
+  {
+    additionalProperties: false,
+    required: []
+  }
+);
+
+const patchBodySchema = Type.Partial(createBodySchema, { additionalProperties: false });
+
+const recordOutputValidator = Object.freeze({
+  schema: recordOutputSchema,
+  normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const normalized = {
+      id: normalizeIfPresent(source.id, Number),
+      firstName: normalizeOrNull(source.firstName, normalizeText)
+    };
+    const sourceLookupContainer = source[RESOURCE_LOOKUP_CONTAINER_KEY];
+    if (sourceLookupContainer && typeof sourceLookupContainer === "object" && !Array.isArray(sourceLookupContainer)) {
+      normalized[RESOURCE_LOOKUP_CONTAINER_KEY] = sourceLookupContainer;
+    }
+    return normalized;
+  }
+});
+
+const listOutputValidator = createCursorListValidator(recordOutputValidator);
+
+const createBodyValidator = Object.freeze({
+  schema: createBodySchema,
+  normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const normalized = {};
+
+    normalizeIfInSource(source, normalized, "firstName", normalizeText);
+
+    return normalized;
+  }
+});
+
+const patchBodyValidator = Object.freeze({
+  schema: patchBodySchema,
+  normalize: createBodyValidator.normalize
+});
+
+const RESOURCE_FIELD_META = [];
+
+const resource = {
+  resource: "contacts",
+  tableName: "contacts",
+  idColumn: "id",
+  operations: {
+    list: { method: "GET", outputValidator: listOutputValidator },
+    view: { method: "GET", outputValidator: recordOutputValidator },
+    create: { method: "POST", bodyValidator: createBodyValidator, outputValidator: recordOutputValidator },
+    patch: { method: "PATCH", bodyValidator: patchBodyValidator, outputValidator: recordOutputValidator }
+  },
+  fieldMeta: RESOURCE_FIELD_META
+};
+
+export { resource };
+`;
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "crud-server-add-field-"));
+  try {
+    await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeAppFile(appRoot, relativePath, source) {
+  const absolutePath = path.join(appRoot, relativePath);
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, source, "utf8");
+  return absolutePath;
+}
+
+function createSnapshot() {
+  return {
+    tableName: "contacts",
+    idColumn: "id",
+    columns: [
+      { name: "id", key: "id", typeKind: "integer", nullable: false, unsigned: true },
+      { name: "workspace_owner_id", key: "workspaceOwnerId", typeKind: "integer", nullable: true, unsigned: true },
+      { name: "user_owner_id", key: "userOwnerId", typeKind: "integer", nullable: true, unsigned: true },
+      { name: "created_at", key: "createdAt", typeKind: "datetime", nullable: false },
+      { name: "updated_at", key: "updatedAt", typeKind: "datetime", nullable: false },
+      { name: "first_name", key: "firstName", typeKind: "string", nullable: true, maxLength: 160 },
+      { name: "category_id", key: "categoryId", typeKind: "integer", nullable: true, unsigned: true }
+    ],
+    foreignKeys: [
+      {
+        name: "contacts_category_id_foreign",
+        referencedTableName: "customer_categories",
+        columns: [
+          {
+            name: "category_id",
+            referencedName: "id"
+          }
+        ]
+      }
+    ]
+  };
+}
+
+test("add-field patches CRUD resource file using DB snapshot metadata", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/contacts/src/shared/contactResource.js";
+    await writeAppFile(appRoot, resourceFile, RESOURCE_SOURCE);
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-field",
+      args: ["categoryId", resourceFile],
+      options: {},
+      resolveSnapshot: async () => createSnapshot()
+    });
+
+    assert.deepEqual(result.touchedFiles, [resourceFile]);
+
+    const content = await readFile(path.join(appRoot, resourceFile), "utf8");
+    assert.match(content, /categoryId: Type\.Union\(\[Type\.Integer\(\{ minimum: 0 \}\), Type\.Null\(\)\]\)/);
+    assert.match(content, /normalizeIfInSource\(source, normalized, "categoryId", normalizeFiniteInteger\);/);
+    assert.match(content, /categoryId: normalizeOrNull\(source\.categoryId, normalizeFiniteInteger\)/);
+    assert.match(content, /RESOURCE_FIELD_META\.push\(\{/);
+    assert.match(content, /key: "categoryId"/);
+    assert.match(content, /namespace: "customer-categories"/);
+    assert.match(content, /valueKey: "id"/);
+    assert.match(content, /formControl: "autocomplete" \/\/ or "select"/);
+    assert.match(content, /normalizeFiniteInteger/);
+
+    const secondRun = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-field",
+      args: ["categoryId", resourceFile],
+      options: {},
+      resolveSnapshot: async () => createSnapshot()
+    });
+    assert.deepEqual(secondRun.touchedFiles, []);
+  });
+});

package/test/buildTemplateContext.test.js

@@ -1,5 +1,8 @@
 import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 
 import { buildTemplateContext, __testables } from "../src/server/buildTemplateContext.js";
 
@@ -101,7 +104,8 @@ function createSnapshot({
         enumValues: Object.freeze([])
       })
     ]),
-    indexes: Object.freeze([])
+    indexes: Object.freeze([]),
+    foreignKeys: Object.freeze([])
   });
 }
 
@@ -196,9 +200,7 @@ test("buildReplacementsFromSnapshot builds deterministic template replacement pa
   assert.equal(replacements.__JSKIT_CRUD_RESOLVED_OWNERSHIP_FILTER__, "workspace_user");
   assert.match(replacements.__JSKIT_CRUD_MIGRATION_COLUMN_LINES__, /table\.increments\("id"\)/);
   assert.match(replacements.__JSKIT_CRUD_MIGRATION_COLUMN_LINES__, /table\.string\("first_name", 160\)/);
-  assert.match(replacements.__JSKIT_CRUD_REPOSITORY_OUTPUT_KEYS__, /"firstName"/);
-  assert.match(replacements.__JSKIT_CRUD_REPOSITORY_WRITE_KEYS__, /"firstName"/);
-  assert.equal(replacements.__JSKIT_CRUD_REPOSITORY_COLUMN_OVERRIDES__, "{}");
+  assert.equal(replacements.__JSKIT_CRUD_RESOURCE_FIELD_META_PUSH_LINES__, "");
   assert.match(replacements.__JSKIT_CRUD_RESOURCE_OUTPUT_SCHEMA_PROPERTIES__, /updatedAt: Type\.String/);
   assert.match(
     replacements.__JSKIT_CRUD_RESOURCE_OUTPUT_SCHEMA_PROPERTIES__,
@@ -226,6 +228,61 @@ test("buildReplacementsFromSnapshot builds deterministic template replacement pa
     /== null \?/
   );
   assert.equal(replacements.__JSKIT_CRUD_RESOURCE_CREATE_REQUIRED_FIELDS__, "[\"firstName\"]");
+  assert.equal(replacements.__JSKIT_CRUD_MIGRATION_FOREIGN_KEY_LINES__, "");
+});
+
+test("buildReplacementsFromSnapshot renders append-only field meta entries from foreign keys", () => {
+  const snapshot = {
+    ...createSnapshot(),
+    columns: Object.freeze([
+      ...createSnapshot().columns,
+      Object.freeze({
+        name: "vet_id",
+        key: "vetId",
+        dataType: "int",
+        columnType: "int unsigned",
+        typeKind: "integer",
+        nullable: true,
+        hasDefault: false,
+        defaultValue: null,
+        autoIncrement: false,
+        unsigned: true,
+        extra: "",
+        maxLength: null,
+        numericPrecision: 10,
+        numericScale: 0,
+        enumValues: Object.freeze([])
+      })
+    ]),
+    foreignKeys: Object.freeze([
+      Object.freeze({
+        name: "contacts_vet_id_foreign",
+        referencedTableName: "customer_categories",
+        updateRule: "CASCADE",
+        deleteRule: "SET NULL",
+        columns: Object.freeze([
+          Object.freeze({
+            name: "vet_id",
+            referencedName: "id"
+          })
+        ])
+      })
+    ])
+  };
+
+  const replacements = __testables.buildReplacementsFromSnapshot({
+    snapshot,
+    resolvedOwnershipFilter: "workspace_user"
+  });
+
+  assert.match(replacements.__JSKIT_CRUD_RESOURCE_FIELD_META_PUSH_LINES__, /RESOURCE_FIELD_META\.push\(\{/);
+  assert.match(replacements.__JSKIT_CRUD_RESOURCE_FIELD_META_PUSH_LINES__, /key: "vetId"/);
+  assert.match(replacements.__JSKIT_CRUD_RESOURCE_FIELD_META_PUSH_LINES__, /namespace: "customer-categories"/);
+  assert.match(
+    replacements.__JSKIT_CRUD_RESOURCE_FIELD_META_PUSH_LINES__,
+    /formControl: "autocomplete" \/\/ or "select"/
+  );
+  assert.match(replacements.__JSKIT_CRUD_MIGRATION_FOREIGN_KEY_LINES__, /table\.foreign\(\["vet_id"\]/);
 });
 
 test("renderMigrationColumnLine ignores SQL NULL string defaults", () => {
@@ -254,3 +311,140 @@ test("renderMigrationColumnLine ignores SQL NULL string defaults", () => {
 
   assert.equal(line.includes(".defaultTo("), false);
 });
+
+test("buildReplacementsFromSnapshot normalizes nullable temporal inputs without invalid date errors", () => {
+  const snapshot = createSnapshot({
+    hasWorkspaceOwnerColumn: false,
+    hasUserOwnerColumn: false
+  });
+  const temporalColumns = [
+    ...snapshot.columns.filter((column) => column.key !== "updatedAt"),
+    Object.freeze({
+      name: "scheduled_at",
+      key: "scheduledAt",
+      dataType: "datetime",
+      columnType: "datetime",
+      typeKind: "datetime",
+      nullable: true,
+      hasDefault: false,
+      defaultValue: null,
+      autoIncrement: false,
+      unsigned: false,
+      extra: "",
+      maxLength: null,
+      numericPrecision: null,
+      numericScale: null,
+      enumValues: Object.freeze([])
+    }),
+    Object.freeze({
+      name: "birth_date",
+      key: "birthDate",
+      dataType: "date",
+      columnType: "date",
+      typeKind: "date",
+      nullable: true,
+      hasDefault: false,
+      defaultValue: null,
+      autoIncrement: false,
+      unsigned: false,
+      extra: "",
+      maxLength: null,
+      numericPrecision: null,
+      numericScale: null,
+      enumValues: Object.freeze([])
+    }),
+    Object.freeze({
+      name: "preferred_time",
+      key: "preferredTime",
+      dataType: "time",
+      columnType: "time",
+      typeKind: "time",
+      nullable: true,
+      hasDefault: false,
+      defaultValue: null,
+      autoIncrement: false,
+      unsigned: false,
+      extra: "",
+      maxLength: null,
+      numericPrecision: null,
+      numericScale: null,
+      enumValues: Object.freeze([])
+    })
+  ];
+
+  const replacements = __testables.buildReplacementsFromSnapshot({
+    namespace: "contacts",
+    snapshot: {
+      ...snapshot,
+      columns: Object.freeze(temporalColumns)
+    },
+    resolvedOwnershipFilter: "public"
+  });
+
+  assert.match(
+    replacements.__JSKIT_CRUD_RESOURCE_INPUT_NORMALIZATION_LINES__,
+    /normalizeIfInSource\(source, normalized, "scheduledAt", \(value\) => \{ const normalized = normalizeText\(value\); return normalized \? toDatabaseDateTimeUtc\(normalized\) : null; \}\);/
+  );
+  assert.match(
+    replacements.__JSKIT_CRUD_RESOURCE_INPUT_NORMALIZATION_LINES__,
+    /normalizeIfInSource\(source, normalized, "birthDate", \(value\) => \{ const normalized = normalizeText\(value\); return normalized \? toIsoString\(normalized\)\.slice\(0, 10\) : null; \}\);/
+  );
+  assert.match(
+    replacements.__JSKIT_CRUD_RESOURCE_INPUT_NORMALIZATION_LINES__,
+    /normalizeIfInSource\(source, normalized, "preferredTime", \(value\) => \{ const normalized = normalizeText\(value\); return normalized \|\| null; \}\);/
+  );
+});
+
+test("crud repository template defines explicit one-line CRUD methods over repository primitives", async () => {
+  const testDirectory = path.dirname(fileURLToPath(import.meta.url));
+  const templatePath = path.resolve(testDirectory, "..", "templates", "src", "local-package", "server", "repository.js");
+  const templateSource = await readFile(templatePath, "utf8");
+  assert.match(
+    templateSource,
+    /from "@jskit-ai\/crud-core\/server\/repositoryMethods";/
+  );
+  assert.match(templateSource, /const repositoryRuntime = createCrudRepositoryRuntime\(/);
+  assert.match(templateSource, /return crudRepositoryList\(repositoryRuntime, knex, query, options, callOptions\);/);
+  assert.match(templateSource, /return crudRepositoryFindById\(repositoryRuntime, knex, recordId, options, callOptions\);/);
+  assert.match(templateSource, /return crudRepositoryListByIds\(repositoryRuntime, knex, ids, options, callOptions\);/);
+  assert.match(templateSource, /return crudRepositoryCreate\(repositoryRuntime, knex, payload, options, callOptions\);/);
+  assert.match(templateSource, /return crudRepositoryUpdateById\(repositoryRuntime, knex, recordId, patch, options, callOptions\);/);
+  assert.match(templateSource, /return crudRepositoryDeleteById\(repositoryRuntime, knex, recordId, options, callOptions\);/);
+});
+
+test("crud service template defines explicit service methods and semi-explicit default events", async () => {
+  const testDirectory = path.dirname(fileURLToPath(import.meta.url));
+  const templatePath = path.resolve(testDirectory, "..", "templates", "src", "local-package", "server", "service.js");
+  const templateSource = await readFile(templatePath, "utf8");
+
+  assert.match(
+    templateSource,
+    /from "@jskit-ai\/crud-core\/server\/serviceEvents";/
+  );
+  assert.match(
+    templateSource,
+    /from "@jskit-ai\/crud-core\/server\/fieldAccess";/
+  );
+  assert.match(templateSource, /const baseServiceEvents = createCrudServiceEvents\(/);
+  assert.match(templateSource, /const fieldAccessRuntime = createCrudFieldAccessRuntime\(/);
+  assert.match(templateSource, /const serviceEvents = Object\.freeze\(\{/);
+  assert.match(templateSource, /createRecord: \[\.\.\.baseServiceEvents\.createRecord\],/);
+  assert.match(templateSource, /async function listRecords\(query = \{\}, options = \{\}\)/);
+  assert.match(templateSource, /return fieldAccessRuntime\.filterReadableListResult\(result, fieldAccess, \{/);
+  assert.match(templateSource, /const writablePayload = await fieldAccessRuntime\.enforceWritablePayload\(payload, fieldAccess, \{/);
+  assert.match(templateSource, /throw new AppError\(404, "Record not found\."\);/);
+});
+
+test("crud provider template uses shared lookup provider helpers instead of inline wiring", async () => {
+  const testDirectory = path.dirname(fileURLToPath(import.meta.url));
+  const templatePath = path.resolve(testDirectory, "..", "templates", "src", "local-package", "server", "CrudProvider.js");
+  const templateSource = await readFile(templatePath, "utf8");
+
+  assert.match(
+    templateSource,
+    /from "@jskit-ai\/crud-core\/server\/lookupProviders";/
+  );
+  assert.match(templateSource, /resolveLookupProvider: createCrudLookupProviderResolver\(scope\)/);
+  assert.match(templateSource, /return createCrudLookupProvider\(scope\.make\("repository\.\$\{option:namespace\|snake\}"\)\);/);
+  assert.doesNotMatch(templateSource, /normalizePathname\(relation\.apiPath\)/);
+});

package/test/crudResource.test.js

@@ -39,3 +39,9 @@ test("crudResource normalizes list output", () => {
   assert.match(normalized.items[0].updatedAt, /T/);
   assert.equal(normalized.nextCursor, "8");
 });
+
+test("crudResource list operation exposes output validator only", () => {
+  assert.equal(typeof crudResource.operations.list.outputValidator?.normalize, "function");
+  assert.equal(crudResource.operations.list.inputValidator, undefined);
+  assert.deepEqual(crudResource.operations.list.realtime?.events, ["crud.record.changed"]);
+});

package/test/crudServerGuards.test.js

@@ -1,61 +1,55 @@
-import test from "node:test";
+import test, { after } from "node:test";
 import assert from "node:assert/strict";
-import { createActions } from "../src/server/actions.js";
-import { createActionIds } from "../src/server/actionIds.js";
-import { createRepository } from "../src/server/repository.js";
-import { registerRoutes } from "../src/server/registerRoutes.js";
+import { createTemplateServerFixture } from "../test-support/templateServerFixture.js";
 
-test("createActionIds requires explicit actionIdPrefix", () => {
-  assert.throws(
-    () => createActionIds(""),
-    /requires actionIdPrefix/
-  );
-});
-
-test("createRepository requires explicit tableName", () => {
-  const knex = () => {
-    throw new Error("not expected");
-  };
+const fixture = await createTemplateServerFixture();
+const { createActions } = await fixture.importServerModule("actions.js");
+const { createRepository } = await fixture.importServerModule("repository.js");
 
-  assert.throws(
-    () => createRepository(knex, {}),
-    /requires tableName/
-  );
+after(async () => {
+  await fixture.cleanup();
 });
 
-test("createActions requires explicit surface", () => {
-  assert.throws(
-    () =>
-      createActions({
-        actionIdPrefix: "crud.customers"
-      }),
-    /requires a non-empty surface/
-  );
-});
-
-test("registerRoutes requires explicit routeRelativePath and actionIds", () => {
-  const app = {
-    make() {
-      return {
-        register() {}
-      };
+test("template createRepository defaults tableName from resource metadata", () => {
+  const query = {
+    select() {
+      return query;
+    },
+    where() {
+      return query;
+    },
+    orderBy() {
+      return query;
+    },
+    modify(callback) {
+      if (typeof callback === "function") {
+        callback(query);
+      }
+      return query;
+    },
+    limit() {
+      return query;
+    },
+    then(resolve) {
+      return Promise.resolve([]).then(resolve);
     }
   };
+  const tables = [];
+  const knex = (tableName) => {
+    tables.push(tableName);
+    return query;
+  };
 
-  assert.throws(
-    () => registerRoutes(app, {}),
-    /requires routeRelativePath/
-  );
+  const repository = createRepository(knex, {});
+  assert.equal(typeof repository.list, "function");
+  return repository.list({}).then(() => {
+    assert.equal(tables[0], "customers");
+  });
+});
 
+test("template createActions requires explicit surface", () => {
   assert.throws(
-    () =>
-      registerRoutes(app, {
-        routeRelativePath: "/customers",
-        routeSurfaceRequiresWorkspace: true,
-        actionIds: {
-          list: "crud.customers.list"
-        }
-      }),
-    /requires actionIds.view/
+    () => createActions({}),
+    /requires a non-empty surface/
   );
 });

package/test/crudService.test.js

@@ -1,10 +1,17 @@
-import test from "node:test";
+import test, { after } from "node:test";
 import assert from "node:assert/strict";
-import { createService } from "../src/server/service.js";
+import { createTemplateServerFixture } from "../test-support/templateServerFixture.js";
+
+const fixture = await createTemplateServerFixture();
+const { createService, serviceEvents } = await fixture.importServerModule("service.js");
+
+after(async () => {
+  await fixture.cleanup();
+});
 
 test("crudService delegates CRUD operations to the repository", async () => {
   const calls = [];
-  const crudRepository = {
+  const customersRepository = {
     async list(query) {
       calls.push(["list", query]);
       return { items: [], nextCursor: null };
@@ -27,7 +34,7 @@ test("crudService delegates CRUD operations to the repository", async () => {
     }
   };
 
-  const service = createService({ crudRepository });
+  const service = createService({ customersRepository });
 
   const options = {};
   await service.listRecords({ limit: 10 }, options);
@@ -47,7 +54,7 @@ test("crudService delegates CRUD operations to the repository", async () => {
 
 test("crudService throws 404 when a record is missing", async () => {
   const service = createService({
-    crudRepository: {
+    customersRepository: {
       async list() {
         return { items: [], nextCursor: null };
       },
@@ -81,3 +88,84 @@ test("crudService throws 404 when a record is missing", async () => {
     (error) => error?.status === 404 && error?.message === "Record not found."
   );
 });
+
+test("crudService exports default realtime events for create/update/delete", () => {
+  assert.equal(serviceEvents.createRecord[0].realtime.event, "customers.record.changed");
+  assert.equal(serviceEvents.updateRecord[0].realtime.event, "customers.record.changed");
+  assert.equal(serviceEvents.deleteRecord[0].realtime.event, "customers.record.changed");
+});
+
+test("crudService supports optional fieldAccess hooks for writable filtering", async () => {
+  const calls = [];
+  const service = createService({
+    customersRepository: {
+      async list() {
+        return {
+          items: [
+            {
+              id: 1,
+              textField: "A",
+              dateField: "2026-03-11T00:00:00.000Z",
+              numberField: 1
+            }
+          ],
+          nextCursor: null
+        };
+      },
+      async findById() {
+        return {
+          id: 1,
+          textField: "A",
+          dateField: "2026-03-11T00:00:00.000Z",
+          numberField: 1
+        };
+      },
+      async create(payload) {
+        calls.push(payload);
+        return {
+          id: 1,
+          textField: payload.textField || "",
+          dateField: "2026-03-11T00:00:00.000Z",
+          numberField: payload.numberField ?? 0
+        };
+      },
+      async updateById(recordId, payload) {
+        calls.push([recordId, payload]);
+        return {
+          id: recordId,
+          textField: payload.textField || "",
+          dateField: "2026-03-11T00:00:00.000Z",
+          numberField: payload.numberField ?? 0
+        };
+      },
+      async deleteById(recordId) {
+        return { id: recordId, deleted: true };
+      }
+    },
+    fieldAccess: {
+      writable: () => ["textField"],
+      writeMode: "strip"
+    }
+  });
+
+  await service.createRecord(
+    {
+      textField: "Allowed",
+      numberField: 99
+    },
+    {}
+  );
+  await service.updateRecord(
+    2,
+    {
+      textField: "Updated",
+      numberField: 88
+    },
+    {}
+  );
+
+  assert.deepEqual(calls, [
+    { textField: "Allowed" },
+    [2, { textField: "Updated" }]
+  ]);
+});