@jskit-ai/crud-server-generator 0.1.26

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

@@ -0,0 +1,67 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@local/${option:namespace|kebab}",
+  version: "0.1.0",
+  kind: "runtime",
+  description: "App-local CRUD package (${option:namespace|kebab}).",
+  dependsOn: [
+    "@jskit-ai/auth-core",
+    "@jskit-ai/crud-core",
+    "@jskit-ai/database-runtime",
+    "@jskit-ai/http-runtime",
+    "@jskit-ai/realtime",
+    "@jskit-ai/users-core"
+  ],
+  capabilities: {
+    provides: [
+      "crud.${option:namespace|kebab}"
+    ],
+    requires: [
+      "runtime.actions",
+      "runtime.database",
+      "auth.policy",
+      "users.core"
+    ]
+  },
+  runtime: {
+    server: {
+      providers: [
+        {
+          entrypoint: "src/server/${option:namespace|pascal}ServiceProvider.js",
+          export: "${option:namespace|pascal}ServiceProvider"
+        }
+      ]
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/actionIds",
+          summary: "App-local CRUD public action identifiers."
+        },
+        {
+          subpath: "./shared",
+          summary: "App-local CRUD shared resource."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "repository.${option:namespace|snake}",
+          "crud.${option:namespace|snake}"
+        ]
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {},
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: []
+  }
+});

package/templates/src/local-package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@local/${option:namespace|kebab}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./server/actionIds": "./src/server/actionIds.js",
+    "./shared": "./src/shared/index.js"
+  }
+}

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

@@ -0,0 +1,84 @@
+import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
+import { resolveCrudSurfacePolicyFromAppConfig } from "@jskit-ai/crud-core/server/crudModuleConfig";
+import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+import { createRepository } from "./repository.js";
+import {
+  createService,
+  serviceEvents
+} 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}",
+  ownershipFilter: "__JSKIT_CRUD_RESOLVED_OWNERSHIP_FILTER__",
+  relativePath: "/${option:directory-prefix|pathprefix}${option:namespace|kebab}"
+});
+
+function resolveCrudPolicyFromApp(app) {
+  return resolveCrudSurfacePolicyFromAppConfig(CRUD_MODULE_CONFIG, resolveAppConfig(app), {
+    context: "${option:namespace|pascal}ServiceProvider"
+  });
+}
+
+class ${option:namespace|pascal}ServiceProvider {
+  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().");
+    }
+
+    const crudPolicy = resolveCrudPolicyFromApp(app);
+
+    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
+      });
+    });
+
+    app.service(
+      "crud.${option:namespace|snake}",
+      (scope) => {
+        return createService({
+          ${option:namespace|camel}Repository: scope.make("repository.${option:namespace|snake}")
+        });
+      },
+      {
+        events: serviceEvents
+      }
+    );
+
+    app.actions(
+      withActionDefaults(
+        createActions({
+          surface: crudPolicy.surfaceId
+        }),
+        {
+          domain: "crud",
+          dependencies: {
+            ${option:namespace|camel}Service: "crud.${option:namespace|snake}"
+          }
+        }
+      )
+    );
+  }
+
+  boot(app) {
+    const crudPolicy = resolveCrudPolicyFromApp(app);
+    registerRoutes(app, {
+      routeOwnershipFilter: crudPolicy.ownershipFilter,
+      routeSurface: crudPolicy.surfaceId,
+      routeSurfaceRequiresWorkspace: crudPolicy.surfaceDefinition.requiresWorkspace === true,
+      routeRelativePath: crudPolicy.relativePath
+    });
+  }
+}
+
+export { ${option:namespace|pascal}ServiceProvider };

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

@@ -0,0 +1,9 @@
+const actionIds = Object.freeze({
+  list: "crud.${option:namespace|snake}.list",
+  view: "crud.${option:namespace|snake}.view",
+  create: "crud.${option:namespace|snake}.create",
+  update: "crud.${option:namespace|snake}.update",
+  delete: "crud.${option:namespace|snake}.delete"
+});
+
+export { actionIds };

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

@@ -0,0 +1,151 @@
+import {
+  cursorPaginationQueryValidator,
+  recordIdParamsValidator
+} from "@jskit-ai/kernel/shared/validators";
+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 { actionIds } from "./actionIds.js";
+
+function requireActionSurface(surface = "") {
+  const normalizedSurface = String(surface || "").trim().toLowerCase();
+  if (!normalizedSurface) {
+    throw new TypeError("createActions requires a non-empty surface.");
+  }
+
+  return normalizedSurface;
+}
+
+function createActions({ surface = "" } = {}) {
+  const actionSurface = requireActionSurface(surface);
+
+  return Object.freeze([
+    {
+      id: actionIds.list,
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [workspaceSlugParamsValidator, cursorPaginationQueryValidator],
+      outputValidator: ${option:namespace|singular|camel}Resource.operations.list.outputValidator,
+      idempotency: "none",
+      audit: {
+        actionName: actionIds.list
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.listRecords(input, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.view,
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [workspaceSlugParamsValidator, recordIdParamsValidator],
+      outputValidator: ${option:namespace|singular|camel}Resource.operations.view.outputValidator,
+      idempotency: "none",
+      audit: {
+        actionName: actionIds.view
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.getRecord(input.recordId, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.create,
+      version: 1,
+      kind: "command",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [
+        workspaceSlugParamsValidator,
+        {
+          payload: ${option:namespace|singular|camel}Resource.operations.create.bodyValidator
+        }
+      ],
+      outputValidator: ${option:namespace|singular|camel}Resource.operations.create.outputValidator,
+      idempotency: "optional",
+      audit: {
+        actionName: actionIds.create
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.createRecord(input.payload, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.update,
+      version: 1,
+      kind: "command",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [
+        workspaceSlugParamsValidator,
+        recordIdParamsValidator,
+        {
+          patch: ${option:namespace|singular|camel}Resource.operations.patch.bodyValidator
+        }
+      ],
+      outputValidator: ${option:namespace|singular|camel}Resource.operations.patch.outputValidator,
+      idempotency: "optional",
+      audit: {
+        actionName: actionIds.update
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.updateRecord(input.recordId, input.patch, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.delete,
+      version: 1,
+      kind: "command",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [workspaceSlugParamsValidator, recordIdParamsValidator],
+      outputValidator: ${option:namespace|singular|camel}Resource.operations.delete.outputValidator,
+      idempotency: "optional",
+      audit: {
+        actionName: actionIds.delete
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.deleteRecord(input.recordId, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    }
+  ]);
+}
+
+export { createActions };

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

@@ -0,0 +1,197 @@
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+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 { 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";
+
+function registerRoutes(
+  app,
+  {
+    routeOwnershipFilter = "public",
+    routeSurface = "",
+    routeSurfaceRequiresWorkspace = false,
+    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,
+    relativePath: routeRelativePath
+  });
+
+  router.register(
+    "GET",
+    routeBase,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "List records."
+      },
+      paramsValidator: routeParamsValidator,
+      queryValidator: cursorPaginationQueryValidator,
+      responseValidators: withStandardErrorResponses({
+        200: ${option:namespace|singular|camel}Resource.operations.list.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const listInput = {
+        ...buildWorkspaceInputFromRouteParams(request.input.params)
+      };
+      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
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "GET",
+    `${routeBase}/:recordId`,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "View a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      responseValidators: withStandardErrorResponses({
+        200: ${option:namespace|singular|camel}Resource.operations.view.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.view,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "POST",
+    routeBase,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Create a record."
+      },
+      paramsValidator: routeParamsValidator,
+      bodyValidator: ${option:namespace|singular|camel}Resource.operations.create.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          201: ${option:namespace|singular|camel}Resource.operations.create.outputValidator
+        },
+        { includeValidation400: true }
+      )
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.create,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          payload: request.input.body
+        }
+      });
+      reply.code(201).send(response);
+    }
+  );
+
+  router.register(
+    "PATCH",
+    `${routeBase}/:recordId`,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Update a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      bodyValidator: ${option:namespace|singular|camel}Resource.operations.patch.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: ${option:namespace|singular|camel}Resource.operations.patch.outputValidator
+        },
+        { includeValidation400: true }
+      )
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.update,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId,
+          patch: request.input.body
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "DELETE",
+    `${routeBase}/:recordId`,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Delete a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      responseValidators: withStandardErrorResponses({
+        200: ${option:namespace|singular|camel}Resource.operations.delete.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.delete,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { registerRoutes };

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

@@ -0,0 +1,161 @@
+import { toInsertDateTime } from "@jskit-ai/database-runtime/shared";
+import { applyVisibility, applyVisibilityOwners } from "@jskit-ai/database-runtime/shared/visibility";
+import {
+  DEFAULT_LIST_LIMIT,
+  normalizeCrudListLimit,
+  requireCrudTableName,
+  buildWritePayload as baseBuildWritePayload,
+  mapRecordRow as baseMapRecordRow,
+  resolveColumnName,
+  resolveCrudIdColumn
+} from "@jskit-ai/crud-core/server/repositorySupport";
+
+const DEFAULT_ID_COLUMN = __JSKIT_CRUD_ID_COLUMN__;
+const OUTPUT_KEYS = Object.freeze(__JSKIT_CRUD_REPOSITORY_OUTPUT_KEYS__);
+const WRITE_KEYS = Object.freeze(__JSKIT_CRUD_REPOSITORY_WRITE_KEYS__);
+const COLUMN_OVERRIDES = Object.freeze(__JSKIT_CRUD_REPOSITORY_COLUMN_OVERRIDES__);
+const CREATED_AT_COLUMN = __JSKIT_CRUD_REPOSITORY_CREATED_AT_COLUMN__;
+const UPDATED_AT_COLUMN = __JSKIT_CRUD_REPOSITORY_UPDATED_AT_COLUMN__;
+
+const {
+  selectColumns: SELECT_COLUMNS,
+  outputMappings: OUTPUT_MAPPINGS,
+  writeMappings: WRITE_MAPPINGS
+} = buildRepositoryColumnMetadata({
+  outputKeys: OUTPUT_KEYS,
+  writeKeys: WRITE_KEYS,
+  columnOverrides: COLUMN_OVERRIDES
+});
+
+function createRepository(knex, { tableName, idColumn = DEFAULT_ID_COLUMN } = {}) {
+  if (typeof knex !== "function") {
+    throw new TypeError("crudRepository requires knex.");
+  }
+
+  const resolvedTableName = requireCrudTableName(tableName);
+  const resolvedIdColumn = resolveCrudIdColumn(idColumn, { fallback: DEFAULT_ID_COLUMN });
+
+  async function list({ cursor = 0, limit = DEFAULT_LIST_LIMIT } = {}, options = {}) {
+    const client = options?.trx || knex;
+    const normalizedCursor = Number.isInteger(Number(cursor)) && Number(cursor) > 0 ? Number(cursor) : 0;
+    const normalizedLimit = normalizeCrudListLimit(limit);
+    const visible = (queryBuilder) => applyVisibility(queryBuilder, options.visibilityContext);
+
+    let query = client(resolvedTableName)
+      .select(...SELECT_COLUMNS)
+      .where(visible)
+      .orderBy(resolvedIdColumn, "asc")
+      .limit(normalizedLimit + 1);
+
+    if (normalizedCursor > 0) {
+      query = query.where(resolvedIdColumn, ">", normalizedCursor);
+    }
+
+    const rows = await query;
+    const hasMore = rows.length > normalizedLimit;
+    const pageRows = hasMore ? rows.slice(0, normalizedLimit) : rows;
+    const items = pageRows.map((row) => baseMapRecordRow(row, OUTPUT_KEYS, COLUMN_OVERRIDES));
+
+    return {
+      items,
+      nextCursor: hasMore && items.length > 0 ? String(items[items.length - 1].id) : null
+    };
+  }
+
+  async function findById(recordId, options = {}) {
+    const client = options?.trx || knex;
+    const visible = (queryBuilder) => applyVisibility(queryBuilder, options.visibilityContext);
+    const row = await client(resolvedTableName)
+      .select(...SELECT_COLUMNS)
+      .where(visible)
+      .where({
+        [resolvedIdColumn]: Number(recordId)
+      })
+      .first();
+
+    return baseMapRecordRow(row, OUTPUT_KEYS, COLUMN_OVERRIDES);
+  }
+
+  async function create(payload = {}, options = {}) {
+    const client = options?.trx || knex;
+    const timestamp = toInsertDateTime();
+    const insertPayload = baseBuildWritePayload(payload, WRITE_KEYS, COLUMN_OVERRIDES);
+    if (CREATED_AT_COLUMN && !Object.hasOwn(insertPayload, CREATED_AT_COLUMN)) {
+      insertPayload[CREATED_AT_COLUMN] = timestamp;
+    }
+    if (UPDATED_AT_COLUMN && !Object.hasOwn(insertPayload, UPDATED_AT_COLUMN)) {
+      insertPayload[UPDATED_AT_COLUMN] = timestamp;
+    }
+
+    const withOwners = applyVisibilityOwners(insertPayload, options.visibilityContext);
+    const [recordId] = await client(resolvedTableName).insert(withOwners);
+
+    return findById(recordId, {
+      ...options,
+      trx: client
+    });
+  }
+
+  async function updateById(recordId, patch = {}, options = {}) {
+    const client = options?.trx || knex;
+    const dbPatch = baseBuildWritePayload(patch, WRITE_KEYS, COLUMN_OVERRIDES);
+    const visible = (queryBuilder) => applyVisibility(queryBuilder, options.visibilityContext);
+    if (UPDATED_AT_COLUMN) {
+      dbPatch[UPDATED_AT_COLUMN] = toInsertDateTime();
+    }
+
+    if (Object.keys(dbPatch).length < 1) {
+      return findById(recordId, {
+        ...options,
+        trx: client
+      });
+    }
+
+    await client(resolvedTableName)
+      .where(visible)
+      .where({
+        [resolvedIdColumn]: Number(recordId)
+      })
+      .update(dbPatch);
+
+    return findById(recordId, {
+      ...options,
+      trx: client
+    });
+  }
+
+  async function deleteById(recordId, options = {}) {
+    const client = options?.trx || knex;
+    const visible = (queryBuilder) => applyVisibility(queryBuilder, options.visibilityContext);
+    const existing = await findById(recordId, {
+      ...options,
+      trx: client
+    });
+
+    if (!existing) {
+      return null;
+    }
+
+    await client(resolvedTableName)
+      .where(visible)
+      .where({
+        [resolvedIdColumn]: Number(recordId)
+      })
+      .delete();
+
+    return {
+      id: existing.id,
+      deleted: true
+    };
+  }
+
+  return Object.freeze({
+    list,
+    findById,
+    create,
+    updateById,
+    deleteById
+  });
+}
+
+export { createRepository };