@jskit-ai/users-core 0.1.65 → 0.1.66

package/templates/packages/users/package.descriptor.mjs

@@ -9,6 +9,8 @@ export default Object.freeze({
     "@jskit-ai/crud-core",
     "@jskit-ai/database-runtime",
     "@jskit-ai/http-runtime",
+    "@jskit-ai/json-rest-api-core",
+    "@jskit-ai/resource-crud-core",
     "@jskit-ai/users-core"
   ],
   capabilities: {
@@ -18,7 +20,8 @@ export default Object.freeze({
     requires: [
       "runtime.actions",
       "runtime.database",
-      "auth.policy"
+      "auth.policy",
+      "json-rest-api.core"
     ]
   },
   runtime: {
@@ -34,10 +37,6 @@ export default Object.freeze({
   metadata: {
     apiSummary: {
       surfaces: [
-        {
-          subpath: "./server/actionIds",
-          summary: "App-local CRUD public action identifiers."
-        },
         {
           subpath: "./shared",
           summary: "App-local CRUD shared resource."

package/templates/packages/users/package.json

@@ -4,7 +4,6 @@
   "private": true,
   "type": "module",
   "exports": {
-    "./server/actionIds": "./src/server/actionIds.js",
     "./shared": "./src/shared/index.js"
   }
 }

package/templates/packages/users/src/server/UsersProvider.js

@@ -1,17 +1,17 @@
 import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
 import { resolveCrudSurfacePolicyFromAppConfig } from "@jskit-ai/crud-core/server/crudModuleConfig";
 import {
-  createCrudLookupResolver,
-  createCrudLookup
-} from "@jskit-ai/crud-core/server/lookups";
+  INTERNAL_JSON_REST_API,
+  addResourceIfMissing,
+  createJsonRestResourceScopeOptions
+} from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
 import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+import { toDatabaseDateTimeUtc } from "@jskit-ai/database-runtime/shared";
 import { createRepository } from "./repository.js";
-import {
-  createService,
-  serviceEvents
-} from "./service.js";
+import { createService } from "./service.js";
 import { createActions } from "./actions.js";
 import { registerRoutes } from "./registerRoutes.js";
+import { resource } from "../shared/userResource.js";
 
 const CRUD_MODULE_CONFIG = Object.freeze({
   namespace: "users",
@@ -29,25 +29,17 @@ function resolveCrudPolicyFromApp(app) {
 class UsersProvider {
   static id = "crud.users";
 
-  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "local.main"];
+  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "local.main", "json-rest-api.core"];
 
   register(app) {
-    if (!app || typeof app.singleton !== "function" || typeof app.service !== "function" || typeof app.actions !== "function") {
-      throw new Error("UsersProvider requires application singleton()/service()/actions().");
-    }
-
     const crudPolicy = resolveCrudPolicyFromApp(app);
 
     app.singleton("repository.users", (scope) => {
+      const api = scope.make(INTERNAL_JSON_REST_API);
       const knex = scope.make("jskit.database.knex");
-      return createRepository(knex, {
-        resolveLookup: createCrudLookupResolver(scope)
-      });
-    });
-
-    app.singleton("lookup.users", (scope) => {
-      return createCrudLookup(scope.make("repository.users"), {
-        ownershipFilter: crudPolicy.ownershipFilter
+      return createRepository({
+        api,
+        knex
       });
     });
 
@@ -57,9 +49,6 @@ class UsersProvider {
         return createService({
           usersRepository: scope.make("repository.users")
         });
-      },
-      {
-        events: serviceEvents
       }
     );
 
@@ -78,8 +67,18 @@ class UsersProvider {
     );
   }
 
-  boot(app) {
+  async boot(app) {
     const crudPolicy = resolveCrudPolicyFromApp(app);
+    const api = app.make(INTERNAL_JSON_REST_API);
+    await addResourceIfMissing(
+      api,
+      "users",
+      createJsonRestResourceScopeOptions(resource, {
+        writeSerializers: {
+          "datetime-utc": toDatabaseDateTimeUtc
+        }
+      })
+    );
     registerRoutes(app, {
       routeOwnershipFilter: crudPolicy.ownershipFilter,
       routeSurface: crudPolicy.surfaceId,

package/templates/packages/users/src/server/actions.js

@@ -1,67 +1,65 @@
-import { recordIdParamsValidator } from "@jskit-ai/kernel/shared/validators";
+import {
+  composeSchemaDefinitions,
+  recordIdParamsValidator
+} from "@jskit-ai/kernel/shared/validators";
 import {
   createCrudCursorPaginationQueryValidator,
   listSearchQueryValidator
 } from "@jskit-ai/crud-core/server/listQueryValidators";
 import { resource } from "../shared/userResource.js";
-import { actionIds } from "./actionIds.js";
-import { LIST_CONFIG } from "./listConfig.js";
 
-const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator(LIST_CONFIG);
+const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator({
+  orderBy: resource.defaultSort
+});
 const authenticatedPermission = Object.freeze({
   require: "authenticated"
 });
 
-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);
-
+function createActions({ surface } = {}) {
   return Object.freeze([
     {
-      id: actionIds.list,
+      id: "crud.users.list",
       version: 1,
       kind: "query",
       channels: ["api", "automation", "internal"],
-      surfaces: [actionSurface],
+      surfaces: [surface],
       permission: authenticatedPermission,
-      inputValidator: [listCursorPaginationQueryValidator, listSearchQueryValidator],
-      outputValidator: resource.operations.list.outputValidator,
+      input: composeSchemaDefinitions([
+        listCursorPaginationQueryValidator,
+        listSearchQueryValidator
+      ]),
+      output: null,
       idempotency: "none",
       audit: {
-        actionName: actionIds.list
+        actionName: "crud.users.list"
       },
       observability: {},
       async execute(input, context, deps) {
-        return deps.usersService.listRecords(input, {
+        const { workspaceSlug, ...query } = input || {};
+        return deps.usersService.queryDocuments(query, {
           context,
           visibilityContext: context?.visibilityContext
         });
       }
     },
     {
-      id: actionIds.view,
+      id: "crud.users.view",
       version: 1,
       kind: "query",
       channels: ["api", "automation", "internal"],
-      surfaces: [actionSurface],
+      surfaces: [surface],
       permission: authenticatedPermission,
-      inputValidator: recordIdParamsValidator,
-      outputValidator: resource.operations.view.outputValidator,
+      input: composeSchemaDefinitions([
+        recordIdParamsValidator
+      ]),
+      output: null,
       idempotency: "none",
       audit: {
-        actionName: actionIds.view
+        actionName: "crud.users.view"
       },
       observability: {},
       async execute(input, context, deps) {
-        return deps.usersService.getRecord(input.recordId, {
+        return deps.usersService.getDocumentById(input.recordId, {
           context,
           visibilityContext: context?.visibilityContext
         });

package/templates/packages/users/src/server/registerRoutes.js

@@ -1,4 +1,4 @@
-import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/shared/validators/jsonApiRouteTransport";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 import {
   createCrudCursorPaginationQueryValidator,
@@ -6,12 +6,31 @@ import {
 } from "@jskit-ai/crud-core/server/listQueryValidators";
 import { resolveScopedApiBasePath } from "@jskit-ai/kernel/shared/surface";
 import { checkRouteVisibility } from "@jskit-ai/kernel/shared/support/visibility";
-import { recordIdParamsValidator } from "@jskit-ai/kernel/shared/validators";
-import { actionIds } from "./actionIds.js";
-import { LIST_CONFIG } from "./listConfig.js";
+import {
+  composeSchemaDefinitions,
+  recordIdParamsValidator
+} from "@jskit-ai/kernel/shared/validators";
 import { resource } from "../shared/userResource.js";
 
-const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator(LIST_CONFIG);
+const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator({
+  orderBy: resource.defaultSort
+});
+const listRouteQueryValidator = composeSchemaDefinitions([
+  listCursorPaginationQueryValidator,
+  listSearchQueryValidator
+]);
+const RESOURCE_ROUTE_CONTRACT_TYPE = resource.namespace;
+const listRouteContract = createJsonApiResourceRouteContract({
+  type: RESOURCE_ROUTE_CONTRACT_TYPE,
+  query: listRouteQueryValidator,
+  output: resource.operations.view.output,
+  outputKind: "collection"
+});
+const viewRouteContract = createJsonApiResourceRouteContract({
+  type: RESOURCE_ROUTE_CONTRACT_TYPE,
+  output: resource.operations.view.output,
+  outputKind: "record"
+});
 
 function registerRoutes(
   app,
@@ -40,14 +59,11 @@ function registerRoutes(
         tags: ["crud"],
         summary: "List users."
       },
-      queryValidator: [listCursorPaginationQueryValidator, listSearchQueryValidator],
-      responseValidators: withStandardErrorResponses({
-        200: resource.operations.list.outputValidator
-      })
+      ...listRouteContract
     },
     async function (request, reply) {
       const response = await request.executeAction({
-        actionId: actionIds.list,
+        actionId: "crud.users.list",
         input: {
           ...(request.input.query || {})
         }
@@ -67,14 +83,12 @@ function registerRoutes(
         tags: ["crud"],
         summary: "View a user."
       },
-      paramsValidator: recordIdParamsValidator,
-      responseValidators: withStandardErrorResponses({
-        200: resource.operations.view.outputValidator
-      })
+      ...viewRouteContract,
+      params: recordIdParamsValidator
     },
     async function (request, reply) {
       const response = await request.executeAction({
-        actionId: actionIds.view,
+        actionId: "crud.users.view",
         input: {
           recordId: request.input.params.recordId
         }

package/templates/packages/users/src/server/repository.js

@@ -1,40 +1,47 @@
-import { createCrudResourceRuntime } from "@jskit-ai/crud-core/server/resourceRuntime";
+import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
+import {
+  buildJsonRestQueryParams,
+  createJsonRestContext,
+  returnNullWhenJsonRestResourceMissing
+} from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
 import { resource } from "../shared/userResource.js";
-import { LIST_CONFIG } from "./listConfig.js";
 
-const REPOSITORY_CONFIG = Object.freeze({
-  context: "users repository",
-  list: LIST_CONFIG
-});
+const RESOURCE_TYPE = resource.namespace;
 
-function createRepository(knex, options = {}) {
-  const resourceRuntime = createCrudResourceRuntime(resource, knex, {
-    ...options,
-    ...REPOSITORY_CONFIG
-  });
-
-  async function list(query = {}, callOptions = {}) {
-    return resourceRuntime.list(query, callOptions);
-  }
-
-  async function findById(recordId, callOptions = {}) {
-    return resourceRuntime.findById(recordId, callOptions);
-  }
+function createRepository({ api, knex } = {}) {
+  const withTransaction = createWithTransaction(knex);
 
-  async function listByIds(ids = [], callOptions = {}) {
-    return resourceRuntime.listByIds(ids, callOptions);
+  async function queryDocuments(query = {}, options = {}) {
+    return api.resources.users.query(
+      {
+        queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, query),
+        transaction: options?.trx || null,
+        simplified: false
+      },
+      createJsonRestContext(options?.context || null)
+    );
   }
 
-  async function listByForeignIds(ids = [], foreignKey = "", callOptions = {}) {
-    return resourceRuntime.listByForeignIds(ids, foreignKey, callOptions);
+  async function getDocumentById(recordId, options = {}) {
+    return returnNullWhenJsonRestResourceMissing(() =>
+      api.resources.users.get(
+        {
+          id: recordId,
+          queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, {}, {
+            include: options?.include
+          }),
+          transaction: options?.trx || null,
+          simplified: false
+        },
+        createJsonRestContext(options?.context || null)
+      )
+    );
   }
 
   return Object.freeze({
-    withTransaction: resourceRuntime.withTransaction,
-    list,
-    findById,
-    listByIds,
-    listByForeignIds
+    withTransaction,
+    queryDocuments,
+    getDocumentById
   });
 }
 

package/templates/packages/users/src/server/service.js

@@ -1,14 +1,12 @@
-import {
-  createCrudServiceRuntime,
-  crudServiceListRecords,
-  crudServiceGetRecord
-} from "@jskit-ai/crud-core/server/serviceMethods";
-import { resource } from "../shared/userResource.js";
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { returnJsonApiDocument } from "@jskit-ai/http-runtime/shared";
 
-const serviceRuntime = createCrudServiceRuntime(resource, {
-  context: "usersService"
-});
-const serviceEvents = Object.freeze({});
+function return404IfNotFound(document = null) {
+  if (!document) {
+    throw new AppError(404, "Document not found.");
+  }
+  return document;
+}
 
 function createService({ usersRepository } = {}) {
   if (!usersRepository) {
@@ -16,13 +14,20 @@ function createService({ usersRepository } = {}) {
   }
 
   return Object.freeze({
-    listRecords(query = {}, options = {}) {
-      return crudServiceListRecords(serviceRuntime, usersRepository, {}, query, options);
+    async queryDocuments(query = {}, options = {}) {
+      return returnJsonApiDocument(await usersRepository.queryDocuments(query, {
+        trx: options?.trx || null,
+        context: options?.context || null
+      }));
     },
-    getRecord(recordId, options = {}) {
-      return crudServiceGetRecord(serviceRuntime, usersRepository, {}, recordId, options);
+    async getDocumentById(recordId, options = {}) {
+      return returnJsonApiDocument(return404IfNotFound(await usersRepository.getDocumentById(recordId, {
+        trx: options?.trx || null,
+        context: options?.context || null,
+        include: options?.include
+      })));
     }
   });
 }
 
-export { createService, serviceEvents };
+export { createService };

package/templates/packages/users/src/shared/userResource.js

@@ -1,74 +1,61 @@
-import { Type } from "typebox";
-import { toIsoString } from "@jskit-ai/database-runtime/shared";
-import {
-  createCursorListValidator,
-  normalizeObjectInput,
-  recordIdSchema
-} from "@jskit-ai/kernel/shared/validators";
-import {
-  normalizeIfPresent,
-  normalizeRecordId,
-  normalizeText
-} from "@jskit-ai/kernel/shared/support/normalize";
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
 
-const recordOutputSchema = Type.Object(
-  {
-    id: recordIdSchema,
-    name: Type.String({ minLength: 1 }),
-    email: Type.String(),
-    username: Type.String(),
-    createdAt: Type.String({ format: "date-time", minLength: 1 })
-  },
-  { additionalProperties: false }
-);
-
-const createBodySchema = Type.Object({}, { additionalProperties: false });
-
-const recordOutputValidator = Object.freeze({
-  schema: recordOutputSchema,
-  normalize(payload = {}) {
-    const source = normalizeObjectInput(payload);
-
-    return {
-      id: normalizeIfPresent(source.id, normalizeRecordId),
-      name: normalizeText(source.name || source.email || source.username || source.id),
-      email: normalizeText(source.email),
-      username: normalizeText(source.username),
-      createdAt: normalizeIfPresent(source.createdAt, toIsoString)
-    };
-  }
-});
-
-const createBodyValidator = Object.freeze({
-  schema: createBodySchema,
-  normalize: normalizeObjectInput
-});
-
-const resource = Object.freeze({
+const resource = defineCrudResource({
   namespace: "users",
   tableName: "users",
-  idColumn: "id",
-  operations: Object.freeze({
-    list: Object.freeze({
-      method: "GET",
-      outputValidator: createCursorListValidator(recordOutputValidator)
-    }),
-    view: Object.freeze({
-      method: "GET",
-      outputValidator: recordOutputValidator
-    }),
-    create: Object.freeze({
-      method: "POST",
-      bodyValidator: createBodyValidator,
-      outputValidator: recordOutputValidator
-    })
-  }),
-  fieldMeta: Object.freeze([
-    Object.freeze({
-      key: "name",
-      repository: { column: "display_name" }
-    })
-  ])
+  crudOperations: ["list", "view", "create"],
+  schema: {
+    name: {
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: 160,
+      actualField: "display_name",
+      search: true,
+      operations: {
+        output: { required: false }
+      }
+    },
+    email: {
+      type: "string",
+      required: true,
+      search: true,
+      operations: {
+        output: { required: false }
+      }
+    },
+    username: {
+      type: "string",
+      required: true,
+      search: true,
+      operations: {
+        output: { required: false }
+      }
+    },
+    createdAt: {
+      type: "dateTime",
+      required: true,
+      storage: { writeSerializer: "datetime-utc" },
+      operations: {
+        output: { required: true }
+      }
+    }
+  },
+  searchSchema: {
+    id: {
+      type: "id",
+      actualField: "id"
+    },
+    q: {
+      type: "string",
+      oneOf: ["name", "email", "username"],
+      filterOperator: "like",
+      splitBy: " ",
+      matchAll: true
+    }
+  },
+  defaultSort: ["name", "email"],
+  autofilter: "public"
 });
 
 export { resource };

package/templates/packages/users-workspace/package.descriptor.mjs

@@ -9,6 +9,8 @@ export default Object.freeze({
     "@jskit-ai/crud-core",
     "@jskit-ai/database-runtime",
     "@jskit-ai/http-runtime",
+    "@jskit-ai/json-rest-api-core",
+    "@jskit-ai/resource-crud-core",
     "@jskit-ai/users-core",
     "@jskit-ai/workspaces-core"
   ],
@@ -19,7 +21,8 @@ export default Object.freeze({
     requires: [
       "runtime.actions",
       "runtime.database",
-      "auth.policy"
+      "auth.policy",
+      "json-rest-api.core"
     ]
   },
   runtime: {
@@ -35,10 +38,6 @@ export default Object.freeze({
   metadata: {
     apiSummary: {
       surfaces: [
-        {
-          subpath: "./server/actionIds",
-          summary: "App-local CRUD public action identifiers."
-        },
         {
           subpath: "./shared",
           summary: "App-local CRUD shared resource."

package/templates/packages/users-workspace/src/server/UsersProvider.js

@@ -1,17 +1,17 @@
 import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
 import { resolveCrudSurfacePolicyFromAppConfig } from "@jskit-ai/crud-core/server/crudModuleConfig";
 import {
-  createCrudLookupResolver,
-  createCrudLookup
-} from "@jskit-ai/crud-core/server/lookups";
+  INTERNAL_JSON_REST_API,
+  addResourceIfMissing,
+  createJsonRestResourceScopeOptions
+} from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
 import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+import { toDatabaseDateTimeUtc } from "@jskit-ai/database-runtime/shared";
 import { createRepository } from "./repository.js";
-import {
-  createService,
-  serviceEvents
-} from "./service.js";
+import { createService } from "./service.js";
 import { createActions } from "./actions.js";
 import { registerRoutes } from "./registerRoutes.js";
+import { resource } from "../shared/userResource.js";
 
 const CRUD_MODULE_CONFIG = Object.freeze({
   namespace: "users",
@@ -29,25 +29,17 @@ function resolveCrudPolicyFromApp(app) {
 class UsersProvider {
   static id = "crud.users";
 
-  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "local.main"];
+  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "local.main", "json-rest-api.core"];
 
   register(app) {
-    if (!app || typeof app.singleton !== "function" || typeof app.service !== "function" || typeof app.actions !== "function") {
-      throw new Error("UsersProvider requires application singleton()/service()/actions().");
-    }
-
     const crudPolicy = resolveCrudPolicyFromApp(app);
 
     app.singleton("repository.users", (scope) => {
+      const api = scope.make(INTERNAL_JSON_REST_API);
       const knex = scope.make("jskit.database.knex");
-      return createRepository(knex, {
-        resolveLookup: createCrudLookupResolver(scope)
-      });
-    });
-
-    app.singleton("lookup.users", (scope) => {
-      return createCrudLookup(scope.make("repository.users"), {
-        ownershipFilter: crudPolicy.ownershipFilter
+      return createRepository({
+        api,
+        knex
       });
     });
 
@@ -57,9 +49,6 @@ class UsersProvider {
         return createService({
           usersRepository: scope.make("repository.users")
         });
-      },
-      {
-        events: serviceEvents
       }
     );
 
@@ -78,8 +67,18 @@ class UsersProvider {
     );
   }
 
-  boot(app) {
+  async boot(app) {
     const crudPolicy = resolveCrudPolicyFromApp(app);
+    const api = app.make(INTERNAL_JSON_REST_API);
+    await addResourceIfMissing(
+      api,
+      "users",
+      createJsonRestResourceScopeOptions(resource, {
+        writeSerializers: {
+          "datetime-utc": toDatabaseDateTimeUtc
+        }
+      })
+    );
     registerRoutes(app, {
       routeOwnershipFilter: crudPolicy.ownershipFilter,
       routeSurface: crudPolicy.surfaceId,