@jskit-ai/kernel 0.1.55 → 0.1.57

package/shared/validators/mergeObjectSchemas.test.js

@@ -1,22 +1,29 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { Type } from "typebox";
 import { mergeObjectSchemas } from "./mergeObjectSchemas.js";
 
 test("mergeObjectSchemas merges disjoint object schemas", () => {
   const mergedSchema = mergeObjectSchemas([
-    Type.Object(
-      {
-        cursor: Type.Optional(Type.String({ minLength: 1 }))
-      },
-      { additionalProperties: false }
-    ),
-    Type.Object(
-      {
-        search: Type.Optional(Type.String({ minLength: 1 }))
-      },
-      { additionalProperties: false }
-    )
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        cursor: {
+          type: "string",
+          minLength: 1
+        }
+      }
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        search: {
+          type: "string",
+          minLength: 1
+        }
+      }
+    }
   ]);
 
   assert.equal(mergedSchema.type, "object");
@@ -28,18 +35,28 @@ test("mergeObjectSchemas merges disjoint object schemas", () => {
 
 test("mergeObjectSchemas preserves required fields through merged property definitions", () => {
   const mergedSchema = mergeObjectSchemas([
-    Type.Object(
-      {
-        workspaceSlug: Type.String({ minLength: 1 })
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        workspaceSlug: {
+          type: "string",
+          minLength: 1
+        }
       },
-      { additionalProperties: false }
-    ),
-    Type.Object(
-      {
-        inviteId: Type.String({ minLength: 1 })
+      required: ["workspaceSlug"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        inviteId: {
+          type: "string",
+          minLength: 1
+        }
       },
-      { additionalProperties: false }
-    )
+      required: ["inviteId"]
+    }
   ]);
 
   assert.deepEqual(mergedSchema.required, ["workspaceSlug", "inviteId"]);
@@ -49,18 +66,26 @@ test("mergeObjectSchemas rejects duplicate properties with different schema obje
   assert.throws(
     () =>
       mergeObjectSchemas([
-        Type.Object(
-          {
-            workspaceSlug: Type.Optional(Type.String({ minLength: 1 }))
-          },
-          { additionalProperties: false }
-        ),
-        Type.Object(
-          {
-            workspaceSlug: Type.Optional(Type.String({ minLength: 2 }))
-          },
-          { additionalProperties: false }
-        )
+        {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            workspaceSlug: {
+              type: "string",
+              minLength: 1
+            }
+          }
+        },
+        {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            workspaceSlug: {
+              type: "string",
+              minLength: 2
+            }
+          }
+        }
       ]),
     /duplicate property "workspaceSlug"/
   );

package/shared/validators/recordIdParamsValidator.js

@@ -1,64 +1,34 @@
-import { Type } from "typebox";
-import { normalizeObjectInput } from "./inputNormalization.js";
-import { normalizePositiveInteger, normalizeRecordId } from "../support/normalize.js";
+import { createSchema } from "json-rest-schema";
+import { deepFreeze } from "../support/deepFreeze.js";
 
 const RECORD_ID_PATTERN = "^[1-9][0-9]*$";
 
-const recordIdSchema = Type.String({
+const recordIdSchema = deepFreeze({
+  type: "string",
   minLength: 1,
   pattern: RECORD_ID_PATTERN
 });
 
 const recordIdInputSchema = recordIdSchema;
 
-const nullableRecordIdSchema = Type.Union([recordIdSchema, Type.Null()]);
-const nullableRecordIdInputSchema = Type.Union([recordIdInputSchema, Type.Null()]);
-
-const positiveIntegerValidator = Object.freeze({
-  schema: Type.Union([
-    Type.Integer({ minimum: 1 }),
-    Type.String({ minLength: 1, pattern: RECORD_ID_PATTERN })
-  ]),
-  normalize(value) {
-    return normalizePositiveInteger(value);
-  }
-});
-
-const recordIdValidator = Object.freeze({
-  schema: recordIdInputSchema,
-  normalize(value) {
-    return normalizeRecordId(value, {
-      fallback: ""
-    });
-  }
+const nullableRecordIdSchema = deepFreeze({
+  ...recordIdSchema,
+  nullable: true
 });
 
-const nullableRecordIdValidator = Object.freeze({
-  schema: nullableRecordIdInputSchema,
-  normalize(value) {
-    return normalizeRecordId(value, {
-      fallback: null
-    });
-  }
-});
-
-const recordIdParamsValidator = Object.freeze({
-  schema: Type.Object(
-    {
-      recordId: Type.Optional(recordIdInputSchema)
-    },
-    { additionalProperties: false }
-  ),
-  normalize(input = {}) {
-    const source = normalizeObjectInput(input);
-    const normalized = {};
+const nullableRecordIdInputSchema = nullableRecordIdSchema;
 
-    if (Object.hasOwn(source, "recordId")) {
-      normalized.recordId = recordIdValidator.normalize(source.recordId);
+const recordIdParamsValidator = deepFreeze({
+  schema: createSchema({
+    recordId: {
+      ...recordIdSchema,
+      required: true,
+      messages: {
+        pattern: "Record id must be a canonical positive integer string."
+      }
     }
-
-    return normalized;
-  }
+  }),
+  mode: "patch"
 });
 
 export {
@@ -67,8 +37,5 @@ export {
   recordIdInputSchema,
   nullableRecordIdSchema,
   nullableRecordIdInputSchema,
-  recordIdValidator,
-  nullableRecordIdValidator,
-  recordIdParamsValidator,
-  positiveIntegerValidator
+  recordIdParamsValidator
 };

package/shared/validators/recordIdParamsValidator.test.js

@@ -4,20 +4,25 @@ import assert from "node:assert/strict";
 import { recordIdParamsValidator } from "./recordIdParamsValidator.js";
 
 test("recordIdParamsValidator normalizes canonical string ids", () => {
-  assert.deepEqual(recordIdParamsValidator.normalize({ recordId: "42" }), {
+  const { validatedObject, errors } = recordIdParamsValidator.schema.patch({ recordId: "42" });
+  assert.deepEqual(errors, {});
+  assert.deepEqual(validatedObject, {
     recordId: "42"
   });
 });
 
 test("recordIdParamsValidator rejects invalid ids", () => {
-  assert.deepEqual(recordIdParamsValidator.normalize({ recordId: "nope" }), {
-    recordId: ""
-  });
-  assert.deepEqual(recordIdParamsValidator.normalize({ recordId: 42 }), {
-    recordId: ""
-  });
+  const invalidString = recordIdParamsValidator.schema.patch({ recordId: "nope" });
+  assert.equal(invalidString.validatedObject.recordId, "nope");
+  assert.equal(invalidString.errors.recordId?.code, "PATTERN");
+
+  const numericId = recordIdParamsValidator.schema.patch({ recordId: 42 });
+  assert.equal(numericId.validatedObject.recordId, "42");
+  assert.deepEqual(numericId.errors, {});
 });
 
 test("recordIdParamsValidator keeps absent key absent", () => {
-  assert.deepEqual(recordIdParamsValidator.normalize({}), {});
+  const { validatedObject, errors } = recordIdParamsValidator.schema.patch({});
+  assert.deepEqual(errors, {});
+  assert.deepEqual(validatedObject, {});
 });

package/shared/validators/resourceRequiredMetadata.js

@@ -23,9 +23,9 @@ function deriveResourceRequiredMetadata(resourceSchema) {
     ? resourceSchema.operations
     : null;
 
-  const createSchema = operations?.create?.bodyValidator?.schema;
-  const replaceSchema = operations?.replace?.bodyValidator?.schema;
-  const patchSchema = operations?.patch?.bodyValidator?.schema;
+  const createSchema = operations?.create?.body?.schema;
+  const replaceSchema = operations?.replace?.body?.schema;
+  const patchSchema = operations?.patch?.body?.schema;
 
   return Object.freeze({
     create: deriveRequiredFieldsFromSchema(createSchema),

package/shared/validators/resourceRequiredMetadata.test.js

@@ -1,6 +1,5 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { Type } from "typebox";
 import {
   normalizeRequiredFieldList,
   deriveRequiredFieldsFromSchema,
@@ -16,28 +15,42 @@ test("normalizeRequiredFieldList trims, dedupes, and drops empty entries", () =>
 });
 
 test("deriveRequiredFieldsFromSchema reads schema.required", () => {
-  const schema = Type.Object({
-    name: Type.String(),
-    color: Type.String(),
-    optionalField: Type.Optional(Type.String())
-  });
+  const schema = {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      color: { type: "string" },
+      optionalField: { type: "string" }
+    },
+    required: ["name", "color"]
+  };
 
   assert.deepEqual(deriveRequiredFieldsFromSchema(schema), ["name", "color"]);
-  assert.deepEqual(deriveRequiredFieldsFromSchema(Type.Partial(schema)), []);
+  assert.deepEqual(deriveRequiredFieldsFromSchema({
+    ...schema,
+    required: []
+  }), []);
 });
 
 test("deriveResourceRequiredMetadata reads create/replace/patch operation body schemas", () => {
-  const fullSchema = Type.Object({
-    name: Type.String(),
-    color: Type.String(),
-    invitesEnabled: Type.Boolean()
-  });
-  const patchSchema = Type.Partial(fullSchema);
+  const fullSchema = {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      color: { type: "string" },
+      invitesEnabled: { type: "boolean" }
+    },
+    required: ["name", "color", "invitesEnabled"]
+  };
+  const patchSchema = {
+    ...fullSchema,
+    required: []
+  };
   const resource = {
     operations: {
-      create: { bodyValidator: { schema: fullSchema } },
-      replace: { bodyValidator: { schema: fullSchema } },
-      patch: { bodyValidator: { schema: patchSchema } }
+      create: { body: { schema: fullSchema } },
+      replace: { body: { schema: fullSchema } },
+      patch: { body: { schema: patchSchema } }
     }
   };
 

package/shared/validators/schemaDefinitions.js

@@ -0,0 +1,126 @@
+import { normalizeObject, normalizeText } from "../support/normalize.js";
+import {
+  executeSchemaDefinition,
+  isJsonRestSchemaInstance,
+  normalizeJsonRestSchemaFieldErrors,
+  resolveSchemaDefinitionMode,
+  resolveSchemaDefinitionTransportSchema
+} from "./jsonRestSchemaSupport.js";
+
+function isSchemaDefinitionObject(value) {
+  return Boolean(value) &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    (
+      Object.prototype.hasOwnProperty.call(value, "schema") ||
+      Object.prototype.hasOwnProperty.call(value, "mode")
+    );
+}
+
+function normalizeSingleSchemaDefinition(value, { context = "schema definition", defaultMode = "" } = {}) {
+  if (value == null) {
+    return null;
+  }
+
+  if (!isSchemaDefinitionObject(value)) {
+    throw new TypeError(`${context} must be a schema definition object.`);
+  }
+
+  const source = normalizeObject(value);
+
+  if (!Object.prototype.hasOwnProperty.call(source, "schema")) {
+    throw new TypeError(`${context}.schema is required.`);
+  }
+
+  if (!isJsonRestSchemaInstance(source.schema)) {
+    throw new TypeError(`${context}.schema must be a json-rest-schema schema instance.`);
+  }
+
+  const normalized = {
+    schema: source.schema
+  };
+
+  const resolvedDefaultMode = normalizeText(defaultMode).toLowerCase();
+  normalized.mode = resolveSchemaDefinitionMode(source, {
+    defaultMode: resolvedDefaultMode || "patch",
+    context: `${context}.mode`
+  });
+
+  return Object.freeze(normalized);
+}
+
+function normalizeSchemaDefinition(value, {
+  context = "schema definition",
+  defaultMode = ""
+} = {}) {
+  return normalizeSingleSchemaDefinition(value, {
+    context,
+    defaultMode
+  });
+}
+
+function resolveSchemaTransportSchemaDefinition(value, {
+  context = "schema definition",
+  defaultMode = ""
+} = {}) {
+  const normalized = normalizeSchemaDefinition(value, {
+    context,
+    defaultMode
+  });
+
+  if (!normalized) {
+    return undefined;
+  }
+
+  return resolveSchemaDefinitionTransportSchema(normalized, {
+    defaultMode: defaultMode || "patch",
+    context: `${context}.mode`
+  });
+}
+
+function resolveStructuredSchemaTransportSchema(value, {
+  context = "schema definition",
+  defaultMode = ""
+} = {}) {
+  return resolveSchemaTransportSchemaDefinition(value, {
+    context,
+    defaultMode
+  });
+}
+
+function hasJsonRestSchemaDefinition(value) {
+  try {
+    return Boolean(normalizeSchemaDefinition(value));
+  } catch {
+    return false;
+  }
+}
+
+function executeJsonRestSchemaDefinition(value, payload, {
+  context = "schema definition",
+  defaultMode = ""
+} = {}) {
+  const normalized = normalizeSchemaDefinition(value, {
+    context,
+    defaultMode
+  });
+
+  if (!normalized) {
+    return null;
+  }
+
+  return executeSchemaDefinition(normalized, payload, {
+    defaultMode: defaultMode || "patch",
+    context: `${context}.mode`
+  });
+}
+
+export {
+  hasJsonRestSchemaDefinition,
+  normalizeSingleSchemaDefinition,
+  normalizeSchemaDefinition,
+  resolveSchemaTransportSchemaDefinition,
+  resolveStructuredSchemaTransportSchema,
+  executeJsonRestSchemaDefinition,
+  normalizeJsonRestSchemaFieldErrors
+};

package/shared/validators/schemaDefinitions.test.js

@@ -0,0 +1,51 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createSchema } from "json-rest-schema";
+import {
+  normalizeSingleSchemaDefinition,
+  resolveSchemaTransportSchemaDefinition
+} from "./schemaDefinitions.js";
+
+test("normalizeSingleSchemaDefinition validates mode eagerly", () => {
+  const definition = {
+    schema: createSchema({
+      name: { type: "string", required: true, minLength: 1 }
+    }),
+    mode: "wrong"
+  };
+
+  assert.throws(
+    () => normalizeSingleSchemaDefinition(definition, {
+      context: "test.definition"
+    }),
+    /test\.definition\.mode must be one of: create, replace, patch\./
+  );
+});
+
+test("normalizeSingleSchemaDefinition preserves valid normalized mode", () => {
+  const definition = normalizeSingleSchemaDefinition({
+    schema: createSchema({
+      name: { type: "string", required: true, minLength: 1 }
+    }),
+    mode: " Replace "
+  }, {
+    context: "test.definition"
+  });
+
+  assert.equal(definition.mode, "replace");
+});
+
+test("resolveSchemaTransportSchemaDefinition still resolves valid definitions", () => {
+  const transportSchema = resolveSchemaTransportSchemaDefinition({
+    schema: createSchema({
+      name: { type: "string", required: true, minLength: 1 }
+    }),
+    mode: "patch"
+  }, {
+    context: "test.definition"
+  });
+
+  assert.equal(transportSchema.type, "object");
+  assert.equal(transportSchema.additionalProperties, false);
+  assert.equal(transportSchema.properties.name.type, "string");
+});

package/shared/validators/schemaPayloadValidation.js

@@ -0,0 +1,65 @@
+import {
+  executeJsonRestSchemaDefinition,
+  normalizeJsonRestSchemaFieldErrors
+} from "./schemaDefinitions.js";
+
+function buildSchemaValidationError({
+  message = "Schema validation failed.",
+  fieldErrors = null,
+  errors = null,
+  cause,
+  statusCode = null
+} = {}) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  if (Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599) {
+    error.statusCode = statusCode;
+  }
+  if (fieldErrors && typeof fieldErrors === "object") {
+    error.fieldErrors = fieldErrors;
+    error.details = {
+      ...(error.details || {}),
+      fieldErrors
+    };
+  } else if (errors !== null && errors !== undefined) {
+    error.details = {
+      ...(error.details || {}),
+      errors
+    };
+  }
+
+  return error;
+}
+
+function validateSchemaPayload(schemaDefinition, payload, {
+  phase = "input",
+  context = "schema definition",
+  statusCode = null
+} = {}) {
+  if (schemaDefinition == null) {
+    return payload;
+  }
+
+  const result = executeJsonRestSchemaDefinition(schemaDefinition, payload, {
+    defaultMode: phase === "output" ? "replace" : "patch",
+    context
+  });
+
+  if (!result) {
+    throw new TypeError(`${context}.schema must be a json-rest-schema schema instance.`);
+  }
+
+  const fieldErrors = normalizeJsonRestSchemaFieldErrors(result?.errors, schemaDefinition);
+  if (Object.keys(fieldErrors).length > 0) {
+    throw buildSchemaValidationError({
+      fieldErrors,
+      statusCode
+    });
+  }
+
+  return result?.validatedObject ?? payload;
+}
+
+export {
+  buildSchemaValidationError,
+  validateSchemaPayload
+};

package/test/barrelExposure.test.js

@@ -47,6 +47,36 @@ const BARREL_EXPECTATIONS = Object.freeze([
       "withActionDefaults"
     ])
   }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "shared", "validators", "index.js"),
+    expectedExports: Object.freeze([
+      "HTML_TIME_STRING_SCHEMA",
+      "NULLABLE_HTML_TIME_STRING_SCHEMA",
+      "RECORD_ID_PATTERN",
+      "buildSchemaValidationError",
+      "composeSchemaDefinitions",
+      "createCursorListValidator",
+      "createSchema",
+      "cursorPaginationQueryValidator",
+      "deriveRequiredFieldsFromSchema",
+      "deriveResourceRequiredMetadata",
+      "executeJsonRestSchemaDefinition",
+      "hasJsonRestSchemaDefinition",
+      "mergeObjectSchemas",
+      "normalizeObjectInput",
+      "normalizeRequiredFieldList",
+      "normalizeSchemaDefinition",
+      "normalizeSingleSchemaDefinition",
+      "nullableRecordIdInputSchema",
+      "nullableRecordIdSchema",
+      "recordIdInputSchema",
+      "recordIdParamsValidator",
+      "recordIdSchema",
+      "resolveSchemaTransportSchemaDefinition",
+      "resolveStructuredSchemaTransportSchema",
+      "validateSchemaPayload"
+    ])
+  }),
   Object.freeze({
     filePath: path.join(REPO_ROOT, "packages", "kernel", "client", "index.js"),
     expectedExports: Object.freeze([

package/test/routeInputContractGuard.test.js

@@ -13,10 +13,6 @@ const DISALLOWED_PATTERNS = [
   {
     description: "spread pass-through from request.input",
     regex: /\.{3}\s*request\.input\.(body|query|params)\b/g
-  },
-  {
-    description: "whole-section pass-through from request.input",
-    regex: /\binput\s*:\s*request\.input\.(body|query|params)\b/g
   }
 ];
 
@@ -50,13 +46,21 @@ function findLineNumber(sourceText, index) {
   return sourceText.slice(0, index).split("\n").length;
 }
 
-test("server route handlers do not pass through request.input sections", async () => {
+test("server route handlers do not spread request.input sections into ad hoc shapes", async () => {
   const allFiles = await listFilesRecursive(PACKAGES_ROOT);
   const targetFiles = allFiles.filter((absolutePath) => isRouteServerSourceFile(absolutePath));
   const violations = [];
 
   for (const absolutePath of targetFiles) {
-    const sourceText = await readFile(absolutePath, "utf8");
+    let sourceText = "";
+    try {
+      sourceText = await readFile(absolutePath, "utf8");
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
     for (const { regex, description } of DISALLOWED_PATTERNS) {
       regex.lastIndex = 0;
       let match = regex.exec(sourceText);