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

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

@@ -1,157 +1,58 @@
-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__;
+  createCrudRepositoryRuntime,
+  crudRepositoryList,
+  crudRepositoryFindById,
+  crudRepositoryListByIds,
+  crudRepositoryCreate,
+  crudRepositoryUpdateById,
+  crudRepositoryDeleteById
+} from "@jskit-ai/crud-core/server/repositoryMethods";
+import { resource } from "../shared/${option:namespace|singular|camel}Resource.js";
+
+const LIST_CONFIG = Object.freeze({
+  // defaultLimit: 20,
+  // maxLimit: 100,
+  // searchColumns: ["name"]
+});
 
-const {
-  selectColumns: SELECT_COLUMNS,
-  outputMappings: OUTPUT_MAPPINGS,
-  writeMappings: WRITE_MAPPINGS
-} = buildRepositoryColumnMetadata({
-  outputKeys: OUTPUT_KEYS,
-  writeKeys: WRITE_KEYS,
-  columnOverrides: COLUMN_OVERRIDES
+const repositoryRuntime = createCrudRepositoryRuntime(resource, {
+  context: "${option:namespace|snake} repository",
+  list: LIST_CONFIG
 });
 
-function createRepository(knex, { tableName, idColumn = DEFAULT_ID_COLUMN } = {}) {
+function createRepository(knex, options = {}) {
   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 list(query = {}, callOptions = {}) {
+    return crudRepositoryList(repositoryRuntime, knex, query, options, callOptions);
   }
 
-  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 findById(recordId, callOptions = {}) {
+    return crudRepositoryFindById(repositoryRuntime, knex, recordId, options, callOptions);
   }
 
-  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 listByIds(ids = [], callOptions = {}) {
+    return crudRepositoryListByIds(repositoryRuntime, knex, ids, options, callOptions);
   }
 
-  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 create(payload = {}, callOptions = {}) {
+    return crudRepositoryCreate(repositoryRuntime, knex, payload, options, callOptions);
   }
 
-  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();
+  async function updateById(recordId, patch = {}, callOptions = {}) {
+    return crudRepositoryUpdateById(repositoryRuntime, knex, recordId, patch, options, callOptions);
+  }
 
-    return {
-      id: existing.id,
-      deleted: true
-    };
+  async function deleteById(recordId, callOptions = {}) {
+    return crudRepositoryDeleteById(repositoryRuntime, knex, recordId, options, callOptions);
   }
 
   return Object.freeze({
     list,
     findById,
+    listByIds,
     create,
     updateById,
     deleteById

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

@@ -1,54 +1,54 @@
 import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { createCrudServiceEvents } from "@jskit-ai/crud-core/server/serviceEvents";
+import { createCrudFieldAccessRuntime } from "@jskit-ai/crud-core/server/fieldAccess";
+import { resource } from "../shared/${option:namespace|singular|camel}Resource.js";
+
+const baseServiceEvents = createCrudServiceEvents(resource, {
+  context: "${option:namespace|camel}Service"
+});
+const fieldAccessRuntime = createCrudFieldAccessRuntime(resource, {
+  context: "${option:namespace|camel}Service"
+});
 
 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: "${option:namespace|snake}.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: "${option:namespace|snake}.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: "${option:namespace|snake}.record.changed",
-        audience: "event_scope"
-      })
-    })
-  ])
+  createRecord: [...baseServiceEvents.createRecord],
+  updateRecord: [...baseServiceEvents.updateRecord],
+  deleteRecord: [...baseServiceEvents.deleteRecord]
 });
 
-function createService({ ${option:namespace|camel}Repository } = {}) {
+const DEFAULT_FIELD_ACCESS = Object.freeze({
+  // Tip: use createFieldAccessForRoleMatrix(...) from @jskit-ai/crud-core/server/fieldAccess to centralize role matrices.
+  // Example:
+  // const DEFAULT_FIELD_ACCESS = createFieldAccessForRoleMatrix({
+  //   default: {
+  //     readable: { list: ["id", "name"], view: ["id", "name", "email"] },
+  //     writable: { create: ["name", "email"], update: ["name"] }
+  //   },
+  //   admin: {
+  //     readable: "*",
+  //     writable: "*"
+  //   },
+  //   writeMode: "throw" // or "strip"
+  // });
+  // readable: ({ action, context }) => ["id", "name"], // null/"*" means no read filtering
+  // Read redaction behavior: drop optional fields; use null/default for required fields.
+  // writable: ({ action, context }) => ["name"], // null/"*" means no write filtering
+  // writeMode: "throw" // "throw" (default) or "strip"
+});
+
+function createService({ ${option:namespace|camel}Repository, fieldAccess = DEFAULT_FIELD_ACCESS } = {}) {
   if (!${option:namespace|camel}Repository) {
     throw new Error("${option:namespace|camel}Service requires ${option:namespace|camel}Repository.");
   }
 
   async function listRecords(query = {}, options = {}) {
-    return ${option:namespace|camel}Repository.list(query, options);
+    const result = await ${option:namespace|camel}Repository.list(query, options);
+    return fieldAccessRuntime.filterReadableListResult(result, fieldAccess, {
+      action: "list",
+      query,
+      options,
+      context: options?.context
+    });
   }
 
   async function getRecord(recordId, options = {}) {
@@ -56,24 +56,50 @@ function createService({ ${option:namespace|camel}Repository } = {}) {
     if (!record) {
       throw new AppError(404, "Record not found.");
     }
-
-    return record;
+    return fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+      action: "view",
+      recordId,
+      options,
+      context: options?.context
+    });
   }
 
   async function createRecord(payload = {}, options = {}) {
-    const record = await ${option:namespace|camel}Repository.create(payload, options);
+    const writablePayload = await fieldAccessRuntime.enforceWritablePayload(payload, fieldAccess, {
+      action: "create",
+      payload,
+      options,
+      context: options?.context
+    });
+    const record = await ${option:namespace|camel}Repository.create(writablePayload, options);
     if (!record) {
       throw new Error("${option:namespace|camel}Service could not load the created record.");
     }
-    return record;
+    return fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+      action: "create",
+      options,
+      context: options?.context
+    });
   }
 
   async function updateRecord(recordId, payload = {}, options = {}) {
-    const record = await ${option:namespace|camel}Repository.updateById(recordId, payload, options);
+    const writablePayload = await fieldAccessRuntime.enforceWritablePayload(payload, fieldAccess, {
+      action: "update",
+      recordId,
+      payload,
+      options,
+      context: options?.context
+    });
+    const record = await ${option:namespace|camel}Repository.updateById(recordId, writablePayload, options);
     if (!record) {
       throw new AppError(404, "Record not found.");
     }
-    return record;
+    return fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+      action: "update",
+      recordId,
+      options,
+      context: options?.context
+    });
   }
 
   async function deleteRecord(recordId, options = {}) {
@@ -93,4 +119,19 @@ function createService({ ${option:namespace|camel}Repository } = {}) {
   });
 }
 
+// Optional event override example:
+// const serviceEvents = {
+//   ...baseServiceEvents,
+//   createRecord: [
+//     ...baseServiceEvents.createRecord,
+//     {
+//       type: "${option:namespace|snake}.custom",
+//       source: "custom",
+//       entity: "record",
+//       operation: "created",
+//       entityId: ({ result }) => result?.id
+//     }
+//   ]
+// };
+
 export { createService, serviceEvents };

package/templates/src/local-package/shared/crudResource.js

@@ -6,26 +6,13 @@ import {
 } from "@jskit-ai/kernel/shared/validators";
 __JSKIT_CRUD_RESOURCE_NORMALIZE_SUPPORT_IMPORT__
 __JSKIT_CRUD_RESOURCE_JSON_IMPORT__
-function normalizeRecordInput(payload = {}) {
-  const source = normalizeObjectInput(payload);
-  const normalized = {};
 
-__JSKIT_CRUD_RESOURCE_INPUT_NORMALIZATION_LINES__
-
-  return normalized;
-}
-
-function normalizeRecordOutput(payload = {}) {
-  const source = normalizeObjectInput(payload);
-
-  return {
-__JSKIT_CRUD_RESOURCE_OUTPUT_NORMALIZATION_LINES__
-  };
-}
+const RESOURCE_LOOKUP_CONTAINER_KEY = "lookups";
 
 const recordOutputSchema = Type.Object(
   {
 __JSKIT_CRUD_RESOURCE_OUTPUT_SCHEMA_PROPERTIES__
+    [RESOURCE_LOOKUP_CONTAINER_KEY]: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
   },
   { additionalProperties: false }
 );
@@ -46,11 +33,62 @@ const patchBodySchema = Type.Partial(createBodySchema, {
 
 const recordOutputValidator = Object.freeze({
   schema: recordOutputSchema,
-  normalize: normalizeRecordOutput
+  normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const normalized = {
+__JSKIT_CRUD_RESOURCE_OUTPUT_NORMALIZATION_LINES__
+    };
+    if (Object.hasOwn(source, RESOURCE_LOOKUP_CONTAINER_KEY)) {
+      normalized[RESOURCE_LOOKUP_CONTAINER_KEY] = source[RESOURCE_LOOKUP_CONTAINER_KEY];
+    }
+
+    return normalized;
+  }
 });
 
-const ${option:namespace|singular|camel}Resource = {
+const listOutputValidator = createCursorListValidator(recordOutputValidator);
+
+const createBodyValidator = Object.freeze({
+  schema: createBodySchema,
+  normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const normalized = {};
+
+__JSKIT_CRUD_RESOURCE_INPUT_NORMALIZATION_LINES__
+
+    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 RESOURCE_FIELD_META = [];
+
+const resource = {
   resource: "${option:namespace|snake}",
+  tableName: __JSKIT_CRUD_TABLE_NAME__,
+  idColumn: __JSKIT_CRUD_ID_COLUMN__,
   messages: {
     validation: "Fix invalid values and try again.",
     saveSuccess: "Record saved.",
@@ -58,10 +96,20 @@ const ${option:namespace|singular|camel}Resource = {
     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: ["${option:namespace|snake}.record.changed"] // Add more events e.g. for lookup records
+      },
       method: "GET",
-      outputValidator: createCursorListValidator(recordOutputValidator)
+      outputValidator: listOutputValidator
     },
     view: {
       method: "GET",
@@ -69,41 +117,25 @@ const ${option:namespace|singular|camel}Resource = {
     },
     create: {
       method: "POST",
-      bodyValidator: {
-        schema: createBodySchema,
-        normalize: normalizeRecordInput
-      },
+      bodyValidator: createBodyValidator,
       outputValidator: recordOutputValidator
     },
     patch: {
       method: "PATCH",
-      bodyValidator: {
-        schema: patchBodySchema,
-        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: RESOURCE_FIELD_META
 };
 
-export { ${option:namespace|singular|camel}Resource };
+export { resource };
+
+// @jskit-contract crud.resource.field-meta.${option:namespace|snake}.v1
+void RESOURCE_FIELD_META;
+
+__JSKIT_CRUD_RESOURCE_FIELD_META_PUSH_LINES__