@jskit-ai/crud 0.1.4

package/src/server/registerRoutes.js

@@ -0,0 +1,235 @@
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+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(KERNEL_TOKENS.HttpRouter);
+  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 };