@jskit-ai/crud-server-generator 0.1.26

package/src/server/crudModuleConfig.js

@@ -0,0 +1 @@
+export * from "@jskit-ai/crud-core/server/crudModuleConfig";

package/src/server/registerRoutes.js

@@ -0,0 +1,234 @@
+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 { crudResource } from "../shared/crud/crudResource.js";
+
+function joinRoutePath(basePath = "", suffix = "") {
+  const base = String(basePath || "").trim().replace(/\/+$/g, "");
+  const end = String(suffix || "").trim();
+  if (!end) {
+    return base;
+  }
+
+  return `${base}/${end.replace(/^\/+/, "")}`;
+}
+
+function requireRouteRelativePath(routeRelativePath) {
+  const routePath = String(routeRelativePath || "").trim();
+  if (!routePath) {
+    throw new TypeError("registerRoutes requires routeRelativePath.");
+  }
+
+  return routePath;
+}
+
+function requireActionIds(actionIds) {
+  const source = actionIds && typeof actionIds === "object" && !Array.isArray(actionIds) ? actionIds : null;
+  if (!source) {
+    throw new TypeError("registerRoutes requires actionIds.");
+  }
+
+  const requiredKeys = ["list", "view", "create", "update", "delete"];
+  const normalized = {};
+  for (const key of requiredKeys) {
+    const value = String(source[key] || "").trim();
+    if (!value) {
+      throw new TypeError(`registerRoutes requires actionIds.${key}.`);
+    }
+    normalized[key] = value;
+  }
+
+  return Object.freeze(normalized);
+}
+
+function registerRoutes(
+  app,
+  {
+    routeRelativePath,
+    routeOwnershipFilter = "public",
+    routeSurface = "",
+    routeSurfaceRequiresWorkspace = false,
+    actionIds
+  } = {}
+) {
+  if (!app || typeof app.make !== "function") {
+    throw new Error("registerRoutes requires application make().");
+  }
+
+  const router = app.make("jskit.http.router");
+  const relativePath = requireRouteRelativePath(routeRelativePath);
+  const routeBase = resolveApiBasePath({
+    surfaceRequiresWorkspace: routeSurfaceRequiresWorkspace === true,
+    relativePath
+  });
+  const routeVisibility = normalizeScopedRouteVisibility(routeOwnershipFilter, {
+    fallback: "public"
+  });
+  const surface = normalizeSurfaceId(routeSurface);
+  const resolvedActionIds = requireActionIds(actionIds);
+
+  router.register(
+    "GET",
+    routeBase,
+    {
+      auth: "required",
+      surface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "List records."
+      },
+      paramsValidator: routeParamsValidator,
+      queryValidator: cursorPaginationQueryValidator,
+      responseValidators: withStandardErrorResponses({
+        200: crudResource.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: resolvedActionIds.list,
+        input: listInput
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "GET",
+    joinRoutePath(routeBase, ":recordId"),
+    {
+      auth: "required",
+      surface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "View a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      responseValidators: withStandardErrorResponses({
+        200: crudResource.operations.view.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: resolvedActionIds.view,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "POST",
+    routeBase,
+    {
+      auth: "required",
+      surface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Create a record."
+      },
+      paramsValidator: routeParamsValidator,
+      bodyValidator: crudResource.operations.create.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          201: crudResource.operations.create.outputValidator
+        },
+        { includeValidation400: true }
+      )
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: resolvedActionIds.create,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          payload: request.input.body
+        }
+      });
+      reply.code(201).send(response);
+    }
+  );
+
+  router.register(
+    "PATCH",
+    joinRoutePath(routeBase, ":recordId"),
+    {
+      auth: "required",
+      surface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Update a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      bodyValidator: crudResource.operations.patch.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: crudResource.operations.patch.outputValidator
+        },
+        { includeValidation400: true }
+      )
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: resolvedActionIds.update,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId,
+          patch: request.input.body
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "DELETE",
+    joinRoutePath(routeBase, ":recordId"),
+    {
+      auth: "required",
+      surface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Delete a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      responseValidators: withStandardErrorResponses({
+        200: crudResource.operations.delete.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: resolvedActionIds.delete,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { registerRoutes };

package/src/server/repository.js

@@ -0,0 +1,162 @@
+import { toInsertDateTime } from "@jskit-ai/database-runtime/shared";
+import { applyVisibility, applyVisibilityOwners } from "@jskit-ai/database-runtime/shared/visibility";
+import {
+  DEFAULT_LIST_LIMIT,
+  normalizeCrudListLimit,
+  requireCrudTableName
+} from "@jskit-ai/crud-core/server/repositorySupport";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";
+import { pickOwnProperties } from "@jskit-ai/kernel/shared/support";
+
+function mapRecordRow(row) {
+  if (!row) {
+    return null;
+  }
+
+  return {
+    id: row.id,
+    textField: row.text_field,
+    dateField: row.date_field,
+    numberField: row.number_field,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+
+function createRepository(knex, { tableName } = {}) {
+  if (typeof knex !== "function") {
+    throw new TypeError("crudRepository requires knex.");
+  }
+
+  const resolvedTableName = requireCrudTableName(tableName);
+
+  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("id", "text_field", "date_field", "number_field", "created_at", "updated_at")
+      .where(visible)
+      .orderBy("id", "asc")
+      .limit(normalizedLimit + 1);
+
+    if (normalizedCursor > 0) {
+      query = query.where("id", ">", normalizedCursor);
+    }
+
+    const rows = await query;
+    const hasMore = rows.length > normalizedLimit;
+    const pageRows = hasMore ? rows.slice(0, normalizedLimit) : rows;
+    const items = pageRows.map((row) => mapRecordRow(row));
+
+    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("id", "text_field", "date_field", "number_field", "created_at", "updated_at")
+      .where(visible)
+      .where({ id: Number(recordId) })
+      .first();
+
+    return mapRecordRow(row);
+  }
+
+  async function create(payload = {}, options = {}) {
+    const client = options?.trx || knex;
+    const source = normalizeObjectInput(payload);
+    const timestamp = toInsertDateTime();
+    const insertPayload = applyVisibilityOwners(
+      {
+        text_field: source.textField,
+        date_field: source.dateField,
+        number_field: source.numberField,
+        created_at: timestamp,
+        updated_at: timestamp
+      },
+      options.visibilityContext
+    );
+    const [recordId] = await client(resolvedTableName).insert({
+      ...insertPayload
+    });
+
+    return findById(recordId, {
+      ...options,
+      trx: client
+    });
+  }
+
+  async function updateById(recordId, patch = {}, options = {}) {
+    const client = options?.trx || knex;
+    const source = normalizeObjectInput(patch);
+    const dbPatch = {};
+    const patchSource = pickOwnProperties(source, ["textField", "dateField", "numberField"]);
+    if (Object.hasOwn(patchSource, "textField")) {
+      dbPatch.text_field = patchSource.textField;
+    }
+    if (Object.hasOwn(patchSource, "dateField")) {
+      dbPatch.date_field = patchSource.dateField;
+    }
+    if (Object.hasOwn(patchSource, "numberField")) {
+      dbPatch.number_field = patchSource.numberField;
+    }
+    const visible = (queryBuilder) => applyVisibility(queryBuilder, options.visibilityContext);
+
+    if (Object.keys(dbPatch).length === 0) {
+      return findById(recordId, {
+        ...options,
+        trx: client
+      });
+    }
+
+    await client(resolvedTableName)
+      .where(visible)
+      .where({ id: Number(recordId) })
+      .update({
+        ...dbPatch,
+        updated_at: toInsertDateTime()
+      });
+
+    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({ id: Number(recordId) }).delete();
+
+    return {
+      id: existing.id,
+      deleted: true
+    };
+  }
+
+  return Object.freeze({
+    list,
+    findById,
+    create,
+    updateById,
+    deleteById
+  });
+}
+
+export { createRepository };

package/src/server/service.js

@@ -0,0 +1,96 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+
+const serviceEvents = Object.freeze({
+  createRecord: Object.freeze([
+    Object.freeze({
+      type: "entity.changed",
+      source: "crud",
+      entity: "record",
+      operation: "created",
+      entityId: ({ result }) => result?.id,
+      realtime: Object.freeze({
+        event: "crud.record.changed",
+        audience: "event_scope"
+      })
+    })
+  ]),
+  updateRecord: Object.freeze([
+    Object.freeze({
+      type: "entity.changed",
+      source: "crud",
+      entity: "record",
+      operation: "updated",
+      entityId: ({ result }) => result?.id,
+      realtime: Object.freeze({
+        event: "crud.record.changed",
+        audience: "event_scope"
+      })
+    })
+  ]),
+  deleteRecord: Object.freeze([
+    Object.freeze({
+      type: "entity.changed",
+      source: "crud",
+      entity: "record",
+      operation: "deleted",
+      entityId: ({ result }) => result?.id,
+      realtime: Object.freeze({
+        event: "crud.record.changed",
+        audience: "event_scope"
+      })
+    })
+  ])
+});
+
+function createService({ crudRepository } = {}) {
+  if (!crudRepository) {
+    throw new Error("crudService requires crudRepository.");
+  }
+
+  async function listRecords(query = {}, options = {}) {
+    return crudRepository.list(query, options);
+  }
+
+  async function getRecord(recordId, options = {}) {
+    const record = await crudRepository.findById(recordId, options);
+    if (!record) {
+      throw new AppError(404, "Record not found.");
+    }
+
+    return record;
+  }
+
+  async function createRecord(payload = {}, options = {}) {
+    const record = await crudRepository.create(payload, options);
+    if (!record) {
+      throw new Error("crudService could not load the created record.");
+    }
+    return record;
+  }
+
+  async function updateRecord(recordId, payload = {}, options = {}) {
+    const record = await crudRepository.updateById(recordId, payload, options);
+    if (!record) {
+      throw new AppError(404, "Record not found.");
+    }
+    return record;
+  }
+
+  async function deleteRecord(recordId, options = {}) {
+    const deleted = await crudRepository.deleteById(recordId, options);
+    if (!deleted) {
+      throw new AppError(404, "Record not found.");
+    }
+    return deleted;
+  }
+
+  return Object.freeze({
+    listRecords,
+    getRecord,
+    createRecord,
+    updateRecord,
+    deleteRecord
+  });
+}
+
+export { createService, serviceEvents };

package/src/shared/crud/crudResource.js

@@ -0,0 +1,191 @@
+import { Type } from "typebox";
+import {
+  toIsoString,
+  toDatabaseDateTimeUtc
+} from "@jskit-ai/database-runtime/shared";
+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);
+
+  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 recordOutputSchema = Type.Object(
+  {
+    id: Type.Integer({ minimum: 1 }),
+    textField: Type.String({ minLength: 1, maxLength: 160 }),
+    dateField: Type.String({ minLength: 1 }),
+    numberField: Type.Number(),
+    createdAt: Type.String({ minLength: 1 }),
+    updatedAt: Type.String({ minLength: 1 })
+  },
+  { additionalProperties: false }
+);
+
+const recordBodySchema = Type.Object(
+  {
+    textField: Type.String({
+      minLength: 1,
+      maxLength: 160,
+      messages: {
+        required: "Text field is required.",
+        minLength: "Text field is required.",
+        maxLength: "Text field must be at most 160 characters.",
+        default: "Text field is required."
+      }
+    }),
+    dateField: Type.String({
+      minLength: 1,
+      messages: {
+        required: "Date field is required.",
+        minLength: "Date field is required.",
+        default: "Date field is required."
+      }
+    }),
+    numberField: Type.Number({
+      messages: {
+        required: "Number field is required.",
+        default: "Number field must be a valid number."
+      }
+    })
+  },
+  {
+    additionalProperties: false,
+    messages: {
+      additionalProperties: "Unexpected field.",
+      default: "Invalid value."
+    }
+  }
+);
+
+const recordOutputValidator = Object.freeze({
+  schema: recordOutputSchema,
+  normalize: normalizeRecordOutput
+});
+
+const crudResource = {
+  resource: "crud",
+  messages: {
+    validation: "Fix invalid CRUD values and try again.",
+    saveSuccess: "Record saved.",
+    saveError: "Unable to save record.",
+    deleteSuccess: "Record deleted.",
+    deleteError: "Unable to delete record."
+  },
+  operations: {
+    list: {
+      method: "GET",
+      outputValidator: createCursorListValidator(recordOutputValidator)
+    },
+    view: {
+      method: "GET",
+      outputValidator: recordOutputValidator
+    },
+    create: {
+      method: "POST",
+      bodyValidator: {
+        schema: recordBodySchema,
+        normalize: normalizeRecordInput
+      },
+      outputValidator: recordOutputValidator
+    },
+    patch: {
+      method: "PATCH",
+      bodyValidator: {
+        schema: Type.Partial(recordBodySchema, { additionalProperties: false }),
+        normalize: normalizeRecordInput
+      },
+      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
+          };
+        }
+      }
+    }
+  }
+};
+
+export { crudResource };

package/src/shared/index.js

@@ -0,0 +1 @@
+export { crudResource } from "./crud/crudResource.js";

package/templates/migrations/crud_initial.cjs

@@ -0,0 +1,17 @@
+const TABLE_NAME = __JSKIT_CRUD_TABLE_NAME__;
+
+exports.up = async function up(knex) {
+  const hasCrudTable = await knex.schema.hasTable(TABLE_NAME);
+  if (hasCrudTable) {
+    return;
+  }
+
+  await knex.schema.createTable(TABLE_NAME, (table) => {
+__JSKIT_CRUD_MIGRATION_COLUMN_LINES__
+__JSKIT_CRUD_MIGRATION_INDEX_LINES__
+  });
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists(TABLE_NAME);
+};