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

package/src/shared/crud/crudResource.js

@@ -7,76 +7,13 @@ import {
   normalizeObjectInput,
   createCursorListValidator
 } from "@jskit-ai/kernel/shared/validators";
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-
-function normalizeNumberField(value, { fieldLabel = "Number field" } = {}) {
-  const normalized = Number(value);
-  if (!Number.isFinite(normalized)) {
-    throw new TypeError(`${fieldLabel} must be a valid number.`);
-  }
-
-  return normalized;
-}
-
-function normalizeDateTimeField(value, { fieldLabel = "Date field" } = {}) {
-  try {
-    return toIsoString(value);
-  } catch {
-    throw new TypeError(`${fieldLabel} must be a valid date/time.`);
-  }
-}
-
-function normalizeDatabaseDateTimeField(value, { fieldLabel = "Date field" } = {}) {
-  try {
-    return toDatabaseDateTimeUtc(value);
-  } catch {
-    throw new TypeError(`${fieldLabel} must be a valid date/time.`);
-  }
-}
-
-function normalizeRecordInput(payload = {}) {
-  const source = normalizeObjectInput(payload);
-  const normalized = {};
-
-  if (Object.hasOwn(source, "textField")) {
-    normalized.textField = normalizeText(source.textField);
-  }
-
-  if (Object.hasOwn(source, "dateField")) {
-    normalized.dateField = normalizeDatabaseDateTimeField(source.dateField, {
-      fieldLabel: "Date field"
-    });
-  }
-
-  if (Object.hasOwn(source, "numberField")) {
-    normalized.numberField = normalizeNumberField(source.numberField, {
-      fieldLabel: "Number field"
-    });
-  }
-
-  return normalized;
-}
-
-function normalizeRecordOutput(payload = {}) {
-  const source = normalizeObjectInput(payload);
+import {
+  normalizeText,
+  normalizeFiniteNumber,
+  normalizeIfPresent
+} from "@jskit-ai/kernel/shared/support/normalize";
 
-  return {
-    id: Number(source.id),
-    textField: normalizeText(source.textField),
-    dateField: normalizeDateTimeField(source.dateField, {
-      fieldLabel: "Date field"
-    }),
-    numberField: normalizeNumberField(source.numberField, {
-      fieldLabel: "Number field"
-    }),
-    createdAt: normalizeDateTimeField(source.createdAt, {
-      fieldLabel: "Created at"
-    }),
-    updatedAt: normalizeDateTimeField(source.updatedAt, {
-      fieldLabel: "Updated at"
-    })
-  };
-}
+const RESOURCE_LOOKUP_CONTAINER_KEY = "lookups";
 
 const recordOutputSchema = Type.Object(
   {
@@ -85,7 +22,8 @@ const recordOutputSchema = Type.Object(
     dateField: Type.String({ minLength: 1 }),
     numberField: Type.Number(),
     createdAt: Type.String({ minLength: 1 }),
-    updatedAt: Type.String({ minLength: 1 })
+    updatedAt: Type.String({ minLength: 1 }),
+    [RESOURCE_LOOKUP_CONTAINER_KEY]: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
   },
   { additionalProperties: false }
 );
@@ -126,13 +64,79 @@ const recordBodySchema = Type.Object(
   }
 );
 
+const patchBodySchema = Type.Partial(recordBodySchema, { additionalProperties: false });
+
 const recordOutputValidator = Object.freeze({
   schema: recordOutputSchema,
-  normalize: normalizeRecordOutput
+  normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const normalized = {
+      id: Number(source.id),
+      textField: normalizeText(source.textField),
+      dateField: toIsoString(source.dateField),
+      numberField: normalizeFiniteNumber(source.numberField),
+      createdAt: normalizeIfPresent(source.createdAt, toIsoString),
+      updatedAt: normalizeIfPresent(source.updatedAt, toIsoString)
+    };
+    if (Object.hasOwn(source, RESOURCE_LOOKUP_CONTAINER_KEY)) {
+      normalized[RESOURCE_LOOKUP_CONTAINER_KEY] = source[RESOURCE_LOOKUP_CONTAINER_KEY];
+    }
+
+    return normalized;
+  }
 });
 
+const listOutputValidator = createCursorListValidator(recordOutputValidator);
+
+const createBodyValidator = Object.freeze({
+  schema: recordBodySchema,
+  normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const normalized = {};
+
+    if (Object.hasOwn(source, "textField")) {
+      normalized.textField = normalizeText(source.textField);
+    }
+    if (Object.hasOwn(source, "dateField")) {
+      normalized.dateField = toDatabaseDateTimeUtc(source.dateField);
+    }
+    if (Object.hasOwn(source, "numberField")) {
+      normalized.numberField = normalizeFiniteNumber(source.numberField);
+    }
+
+    return normalized;
+  }
+});
+
+const patchBodyValidator = Object.freeze({
+  schema: patchBodySchema,
+  normalize: createBodyValidator.normalize
+});
+
+const deleteOutputValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      id: Type.Integer({ minimum: 1 }),
+      deleted: Type.Literal(true)
+    },
+    { additionalProperties: false }
+  ),
+  normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+
+    return {
+      id: Number(source.id),
+      deleted: true
+    };
+  }
+});
+
+const CRUD_RESOURCE_FIELD_META = [];
+
 const crudResource = {
   resource: "crud",
+  tableName: "crud",
+  idColumn: "id",
   messages: {
     validation: "Fix invalid CRUD values and try again.",
     saveSuccess: "Record saved.",
@@ -140,10 +144,20 @@ const crudResource = {
     deleteSuccess: "Record deleted.",
     deleteError: "Unable to delete record."
   },
+  contract: {
+    lookup: {
+      containerKey: RESOURCE_LOOKUP_CONTAINER_KEY,
+      defaultInclude: "*", // Set "none" to disable lookup hydration unless include=... is passed.
+      maxDepth: 3 // Lower this to limit nested lookup hydration depth.
+    }
+  },
   operations: {
     list: {
+      realtime: {
+        events: ["crud.record.changed"] // Add more events e.g. for lookup records
+      },
       method: "GET",
-      outputValidator: createCursorListValidator(recordOutputValidator)
+      outputValidator: listOutputValidator
     },
     view: {
       method: "GET",
@@ -151,41 +165,22 @@ const crudResource = {
     },
     create: {
       method: "POST",
-      bodyValidator: {
-        schema: recordBodySchema,
-        normalize: normalizeRecordInput
-      },
+      bodyValidator: createBodyValidator,
       outputValidator: recordOutputValidator
     },
     patch: {
       method: "PATCH",
-      bodyValidator: {
-        schema: Type.Partial(recordBodySchema, { additionalProperties: false }),
-        normalize: normalizeRecordInput
-      },
+      bodyValidator: patchBodyValidator,
       outputValidator: recordOutputValidator
     },
     delete: {
       method: "DELETE",
-      outputValidator: {
-        schema: Type.Object(
-          {
-            id: Type.Integer({ minimum: 1 }),
-            deleted: Type.Literal(true)
-          },
-          { additionalProperties: false }
-        ),
-        normalize(payload = {}) {
-          const source = normalizeObjectInput(payload);
-
-          return {
-            id: Number(source.id),
-            deleted: true
-          };
-        }
-      }
+      outputValidator: deleteOutputValidator
     }
-  }
+  },
+  fieldMeta: CRUD_RESOURCE_FIELD_META
 };
 
+void CRUD_RESOURCE_FIELD_META;
+
 export { crudResource };

package/templates/migrations/crud_initial.cjs

@@ -9,6 +9,7 @@ exports.up = async function up(knex) {
   await knex.schema.createTable(TABLE_NAME, (table) => {
 __JSKIT_CRUD_MIGRATION_COLUMN_LINES__
 __JSKIT_CRUD_MIGRATION_INDEX_LINES__
+__JSKIT_CRUD_MIGRATION_FOREIGN_KEY_LINES__
   });
 };
 

package/templates/src/local-package/package.descriptor.mjs

@@ -27,8 +27,8 @@ export default Object.freeze({
     server: {
       providers: [
         {
-          entrypoint: "src/server/${option:namespace|pascal}ServiceProvider.js",
-          export: "${option:namespace|pascal}ServiceProvider"
+          entrypoint: "src/server/${option:namespace|pascal}Provider.js",
+          export: "${option:namespace|pascal}Provider"
         }
       ]
     }

package/templates/src/local-package/server/{CrudServiceProvider.js → CrudProvider.js}

@@ -1,5 +1,9 @@
 import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
 import { resolveCrudSurfacePolicyFromAppConfig } from "@jskit-ai/crud-core/server/crudModuleConfig";
+import {
+  createCrudLookupProviderResolver,
+  createCrudLookupProvider
+} from "@jskit-ai/crud-core/server/lookupProviders";
 import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
 import { createRepository } from "./repository.js";
 import {
@@ -8,8 +12,6 @@ import {
 } from "./service.js";
 import { createActions } from "./actions.js";
 import { registerRoutes } from "./registerRoutes.js";
-const NAMESPACE_${option:namespace|snake|upper}_TABLE_NAME = __JSKIT_CRUD_TABLE_NAME__;
-const NAMESPACE_${option:namespace|snake|upper}_ID_COLUMN = __JSKIT_CRUD_ID_COLUMN__;
 const CRUD_MODULE_CONFIG = Object.freeze({
   namespace: "${option:namespace|snake}",
   surface: "${option:surface|lower}",
@@ -19,18 +21,18 @@ const CRUD_MODULE_CONFIG = Object.freeze({
 
 function resolveCrudPolicyFromApp(app) {
   return resolveCrudSurfacePolicyFromAppConfig(CRUD_MODULE_CONFIG, resolveAppConfig(app), {
-    context: "${option:namespace|pascal}ServiceProvider"
+    context: "${option:namespace|pascal}Provider"
   });
 }
 
-class ${option:namespace|pascal}ServiceProvider {
+class ${option:namespace|pascal}Provider {
   static id = "crud.${option:namespace|snake}";
 
   static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "local.main", "users.core"];
 
   register(app) {
     if (!app || typeof app.singleton !== "function" || typeof app.service !== "function" || typeof app.actions !== "function") {
-      throw new Error("${option:namespace|pascal}ServiceProvider requires application singleton()/service()/actions().");
+      throw new Error("${option:namespace|pascal}Provider requires application singleton()/service()/actions().");
     }
 
     const crudPolicy = resolveCrudPolicyFromApp(app);
@@ -38,11 +40,14 @@ class ${option:namespace|pascal}ServiceProvider {
     app.singleton("repository.${option:namespace|snake}", (scope) => {
       const knex = scope.make("jskit.database.knex");
       return createRepository(knex, {
-        tableName: NAMESPACE_${option:namespace|snake|upper}_TABLE_NAME,
-        idColumn: NAMESPACE_${option:namespace|snake|upper}_ID_COLUMN
+        resolveLookupProvider: createCrudLookupProviderResolver(scope)
       });
     });
 
+    app.singleton("crud.lookup.${option:namespace|snake}", (scope) => {
+      return createCrudLookupProvider(scope.make("repository.${option:namespace|snake}"));
+    });
+
     app.service(
       "crud.${option:namespace|snake}",
       (scope) => {
@@ -81,4 +86,4 @@ class ${option:namespace|pascal}ServiceProvider {
   }
 }
 
-export { ${option:namespace|pascal}ServiceProvider };
+export { ${option:namespace|pascal}Provider };

package/templates/src/local-package/server/actions.js

@@ -2,10 +2,17 @@ import {
   cursorPaginationQueryValidator,
   recordIdParamsValidator
 } from "@jskit-ai/kernel/shared/validators";
+import {
+  listSearchQueryValidator,
+  lookupIncludeQueryValidator,
+  createCrudParentFilterQueryValidator
+} from "@jskit-ai/crud-core/server/listQueryValidators";
 import { workspaceSlugParamsValidator } from "@jskit-ai/users-core/server/validators/routeParamsValidator";
-import { ${option:namespace|singular|camel}Resource } from "../shared/${option:namespace|singular|camel}Resource.js";
+import { resource } from "../shared/${option:namespace|singular|camel}Resource.js";
 import { actionIds } from "./actionIds.js";
 
+const listParentFilterQueryValidator = createCrudParentFilterQueryValidator(resource);
+
 function requireActionSurface(surface = "") {
   const normalizedSurface = String(surface || "").trim().toLowerCase();
   if (!normalizedSurface) {
@@ -28,8 +35,14 @@ function createActions({ surface = "" } = {}) {
       permission: {
         require: "authenticated"
       },
-      inputValidator: [workspaceSlugParamsValidator, cursorPaginationQueryValidator],
-      outputValidator: ${option:namespace|singular|camel}Resource.operations.list.outputValidator,
+      inputValidator: [
+        workspaceSlugParamsValidator,
+        cursorPaginationQueryValidator,
+        listSearchQueryValidator,
+        listParentFilterQueryValidator,
+        lookupIncludeQueryValidator
+      ],
+      outputValidator: resource.operations.list.outputValidator,
       idempotency: "none",
       audit: {
         actionName: actionIds.list
@@ -51,7 +64,7 @@ function createActions({ surface = "" } = {}) {
       permission: {
         require: "authenticated"
       },
-      inputValidator: [workspaceSlugParamsValidator, recordIdParamsValidator],
+      inputValidator: [workspaceSlugParamsValidator, recordIdParamsValidator, lookupIncludeQueryValidator],
       outputValidator: ${option:namespace|singular|camel}Resource.operations.view.outputValidator,
       idempotency: "none",
       audit: {
@@ -61,7 +74,8 @@ function createActions({ surface = "" } = {}) {
       async execute(input, context, deps) {
         return deps.${option:namespace|camel}Service.getRecord(input.recordId, {
           context,
-          visibilityContext: context?.visibilityContext
+          visibilityContext: context?.visibilityContext,
+          include: input.include
         });
       }
     },
@@ -77,10 +91,10 @@ function createActions({ surface = "" } = {}) {
       inputValidator: [
         workspaceSlugParamsValidator,
         {
-          payload: ${option:namespace|singular|camel}Resource.operations.create.bodyValidator
+          payload: resource.operations.create.bodyValidator
         }
       ],
-      outputValidator: ${option:namespace|singular|camel}Resource.operations.create.outputValidator,
+      outputValidator: resource.operations.create.outputValidator,
       idempotency: "optional",
       audit: {
         actionName: actionIds.create
@@ -106,10 +120,10 @@ function createActions({ surface = "" } = {}) {
         workspaceSlugParamsValidator,
         recordIdParamsValidator,
         {
-          patch: ${option:namespace|singular|camel}Resource.operations.patch.bodyValidator
+          patch: resource.operations.patch.bodyValidator
         }
       ],
-      outputValidator: ${option:namespace|singular|camel}Resource.operations.patch.outputValidator,
+      outputValidator: resource.operations.patch.outputValidator,
       idempotency: "optional",
       audit: {
         actionName: actionIds.update
@@ -132,7 +146,7 @@ function createActions({ surface = "" } = {}) {
         require: "authenticated"
       },
       inputValidator: [workspaceSlugParamsValidator, recordIdParamsValidator],
-      outputValidator: ${option:namespace|singular|camel}Resource.operations.delete.outputValidator,
+      outputValidator: resource.operations.delete.outputValidator,
       idempotency: "optional",
       audit: {
         actionName: actionIds.delete

package/templates/src/local-package/server/registerRoutes.js

@@ -1,15 +1,22 @@
 import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import {
+  listSearchQueryValidator,
+  lookupIncludeQueryValidator,
+  createCrudParentFilterQueryValidator
+} from "@jskit-ai/crud-core/server/listQueryValidators";
 import {
   cursorPaginationQueryValidator,
   recordIdParamsValidator
 } from "@jskit-ai/kernel/shared/validators";
 import { routeParamsValidator } from "@jskit-ai/users-core/server/validators/routeParamsValidator";
-import { normalizeScopedRouteVisibility } from "@jskit-ai/users-core/shared/support/usersVisibility";
+import { checkRouteVisibility } from "@jskit-ai/users-core/shared/support/usersVisibility";
 import { buildWorkspaceInputFromRouteParams } from "@jskit-ai/users-core/server/support/workspaceRouteInput";
 import { resolveApiBasePath } from "@jskit-ai/users-core/shared/support/usersApiPaths";
 import { actionIds } from "./actionIds.js";
-import { ${option:namespace|singular|camel}Resource } from "../shared/${option:namespace|singular|camel}Resource.js";
+import { resource } from "../shared/${option:namespace|singular|camel}Resource.js";
+
+const listParentFilterQueryValidator = createCrudParentFilterQueryValidator(resource);
 
 function registerRoutes(
   app,
@@ -20,17 +27,7 @@ function registerRoutes(
     routeRelativePath = ""
   } = {}
 ) {
-  if (!app || typeof app.make !== "function") {
-    throw new Error("registerRoutes requires application make().");
-  }
-  if (!String(routeRelativePath || "").trim()) {
-    throw new Error("registerRoutes requires routeRelativePath.");
-  }
-
   const router = app.make("jskit.http.router");
-  const routeVisibility = normalizeScopedRouteVisibility(routeOwnershipFilter, {
-    fallback: "public"
-  });
   const normalizedRouteSurface = normalizeSurfaceId(routeSurface);
   const routeBase = resolveApiBasePath({
     surfaceRequiresWorkspace: routeSurfaceRequiresWorkspace === true,
@@ -43,27 +40,27 @@ function registerRoutes(
     {
       auth: "required",
       surface: normalizedRouteSurface,
-      visibility: routeVisibility,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
         summary: "List records."
       },
       paramsValidator: routeParamsValidator,
-      queryValidator: cursorPaginationQueryValidator,
+      queryValidator: [
+        cursorPaginationQueryValidator,
+        listSearchQueryValidator,
+        listParentFilterQueryValidator,
+        lookupIncludeQueryValidator
+      ],
       responseValidators: withStandardErrorResponses({
-        200: ${option:namespace|singular|camel}Resource.operations.list.outputValidator
+        200: resource.operations.list.outputValidator
       })
     },
     async function (request, reply) {
       const listInput = {
-        ...buildWorkspaceInputFromRouteParams(request.input.params)
+        ...buildWorkspaceInputFromRouteParams(request.input.params),
+        ...(request.input.query || {})
       };
-      if (request.input.query.cursor != null) {
-        listInput.cursor = request.input.query.cursor;
-      }
-      if (request.input.query.limit != null) {
-        listInput.limit = request.input.query.limit;
-      }
       const response = await request.executeAction({
         actionId: actionIds.list,
         input: listInput
@@ -78,14 +75,15 @@ function registerRoutes(
     {
       auth: "required",
       surface: normalizedRouteSurface,
-      visibility: routeVisibility,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
         summary: "View a record."
       },
       paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      queryValidator: [lookupIncludeQueryValidator],
       responseValidators: withStandardErrorResponses({
-        200: ${option:namespace|singular|camel}Resource.operations.view.outputValidator
+        200: resource.operations.view.outputValidator
       })
     },
     async function (request, reply) {
@@ -93,7 +91,8 @@ function registerRoutes(
         actionId: actionIds.view,
         input: {
           ...buildWorkspaceInputFromRouteParams(request.input.params),
-          recordId: request.input.params.recordId
+          recordId: request.input.params.recordId,
+          ...(request.input.query || {})
         }
       });
       reply.code(200).send(response);
@@ -106,16 +105,16 @@ function registerRoutes(
     {
       auth: "required",
       surface: normalizedRouteSurface,
-      visibility: routeVisibility,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
         summary: "Create a record."
       },
       paramsValidator: routeParamsValidator,
-      bodyValidator: ${option:namespace|singular|camel}Resource.operations.create.bodyValidator,
+      bodyValidator: resource.operations.create.bodyValidator,
       responseValidators: withStandardErrorResponses(
         {
-          201: ${option:namespace|singular|camel}Resource.operations.create.outputValidator
+          201: resource.operations.create.outputValidator
         },
         { includeValidation400: true }
       )
@@ -138,16 +137,16 @@ function registerRoutes(
     {
       auth: "required",
       surface: normalizedRouteSurface,
-      visibility: routeVisibility,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
         summary: "Update a record."
       },
       paramsValidator: [routeParamsValidator, recordIdParamsValidator],
-      bodyValidator: ${option:namespace|singular|camel}Resource.operations.patch.bodyValidator,
+      bodyValidator: resource.operations.patch.bodyValidator,
       responseValidators: withStandardErrorResponses(
         {
-          200: ${option:namespace|singular|camel}Resource.operations.patch.outputValidator
+          200: resource.operations.patch.outputValidator
         },
         { includeValidation400: true }
       )
@@ -171,14 +170,14 @@ function registerRoutes(
     {
       auth: "required",
       surface: normalizedRouteSurface,
-      visibility: routeVisibility,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
         summary: "Delete a record."
       },
       paramsValidator: [routeParamsValidator, recordIdParamsValidator],
       responseValidators: withStandardErrorResponses({
-        200: ${option:namespace|singular|camel}Resource.operations.delete.outputValidator
+        200: resource.operations.delete.outputValidator
       })
     },
     async function (request, reply) {