@jskit-ai/kernel 0.1.55 → 0.1.56

package/shared/validators/composeSchemaDefinitions.test.js

@@ -0,0 +1,156 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSchema } from "json-rest-schema";
+import { composeSchemaDefinitions } from "./composeSchemaDefinitions.js";
+
+test("composeSchemaDefinitions merges multiple schema definitions into one contract", () => {
+  const params = {
+    schema: createSchema({
+      workspaceSlug: {
+        type: "string",
+        required: true,
+        minLength: 1
+      }
+    }),
+    mode: "patch"
+  };
+  const query = {
+    schema: createSchema({
+      q: {
+        type: "string",
+        required: false,
+        minLength: 1
+      }
+    }),
+    mode: "patch"
+  };
+
+  const definition = composeSchemaDefinitions([params, query], {
+    context: "test.compose"
+  });
+
+  assert.equal(definition.mode, "patch");
+  assert.deepEqual(Object.keys(definition.schema.getFieldDefinitions()).sort(), ["q", "workspaceSlug"]);
+});
+
+test("composeSchemaDefinitions preserves isolated schema factory registries", () => {
+  const localSchemaFactory = createSchema.createFactory();
+  localSchemaFactory.addType("scoped-status", (context) => String(context.value).toUpperCase());
+
+  const query = {
+    schema: localSchemaFactory({
+      status: {
+        type: "scoped-status",
+        required: false
+      }
+    }),
+    mode: "patch"
+  };
+  const params = {
+    schema: createSchema({
+      workspaceSlug: {
+        type: "string",
+        required: true,
+        minLength: 1
+      }
+    }),
+    mode: "patch"
+  };
+
+  const definition = composeSchemaDefinitions([params, query], {
+    context: "test.compose"
+  });
+  const { validatedObject } = definition.schema.patch({
+    workspaceSlug: "alpha",
+    status: "active"
+  });
+
+  assert.equal(validatedObject.workspaceSlug, "alpha");
+  assert.equal(validatedObject.status, "ACTIVE");
+});
+
+test("composeSchemaDefinitions rejects duplicate fields", () => {
+  const a = {
+    schema: createSchema({
+      recordId: {
+        type: "string",
+        required: true,
+        minLength: 1
+      }
+    }),
+    mode: "patch"
+  };
+  const b = {
+    schema: createSchema({
+      recordId: {
+        type: "string",
+        required: true,
+        minLength: 1
+      }
+    }),
+    mode: "patch"
+  };
+
+  assert.throws(
+    () => composeSchemaDefinitions([a, b], {
+      mode: "patch",
+      context: "test.compose"
+    }),
+    /test\.compose cannot compose duplicate field "recordId"/
+  );
+});
+
+test("composeSchemaDefinitions defaults to patch when all child definitions use patch mode", () => {
+  const params = {
+    schema: createSchema({
+      workspaceSlug: {
+        type: "string",
+        required: true,
+        minLength: 1
+      }
+    }),
+    mode: "patch"
+  };
+  const query = {
+    schema: createSchema({
+      q: {
+        type: "string",
+        required: false,
+        minLength: 1
+      }
+    }),
+    mode: "patch"
+  };
+
+  const definition = composeSchemaDefinitions([params, query], { context: "test.compose" });
+
+  assert.equal(definition.mode, "patch");
+});
+
+test("composeSchemaDefinitions requires an explicit mode when child definitions are not all patch", () => {
+  const params = {
+    schema: createSchema({
+      workspaceSlug: {
+        type: "string",
+        required: true,
+        minLength: 1
+      }
+    }),
+    mode: "patch"
+  };
+  const body = {
+    schema: createSchema({
+      name: {
+        type: "string",
+        required: true,
+        minLength: 1
+      }
+    }),
+    mode: "create"
+  };
+
+  assert.throws(
+    () => composeSchemaDefinitions([params, body], { context: "test.compose" }),
+    /test\.compose requires an explicit mode unless all schema definitions use patch mode/
+  );
+});

package/shared/validators/createCursorListValidator.js

@@ -1,41 +1,28 @@
-import { Type } from "typebox";
-import { normalizeObjectInput } from "./inputNormalization.js";
-import { normalizeText } from "../support/normalize.js";
+import { createSchema } from "json-rest-schema";
+import { deepFreeze } from "../support/deepFreeze.js";
+import { normalizeSingleSchemaDefinition } from "./schemaDefinitions.js";
 
 function createCursorListValidator(itemValidator) {
-  if (!itemValidator || typeof itemValidator !== "object" || Array.isArray(itemValidator)) {
-    throw new TypeError("createCursorListValidator requires an item validator object.");
-  }
-
-  if (!Object.hasOwn(itemValidator, "schema")) {
-    throw new TypeError("createCursorListValidator requires itemValidator.schema.");
-  }
-
-  const normalizeItem =
-    typeof itemValidator.normalize === "function"
-      ? itemValidator.normalize
-      : function identity(value) {
-          return value;
-        };
-
-  return Object.freeze({
-    get schema() {
-      return Type.Object(
-        {
-          items: Type.Array(itemValidator.schema),
-          nextCursor: Type.Union([Type.String({ minLength: 1 }), Type.Null()])
-        },
-        { additionalProperties: false }
-      );
-    },
-    normalize(payload = {}) {
-      const source = normalizeObjectInput(payload);
+  const itemDefinition = normalizeSingleSchemaDefinition(itemValidator, {
+    context: "cursor list item",
+    defaultMode: "replace"
+  });
 
-      return {
-        items: Array.isArray(source.items) ? source.items.map((entry) => normalizeItem(entry)) : [],
-        nextCursor: normalizeText(source.nextCursor) || null
-      };
-    }
+  return deepFreeze({
+    schema: createSchema({
+      items: {
+        type: "array",
+        required: true,
+        items: itemDefinition.schema
+      },
+      nextCursor: {
+        type: "string",
+        required: false,
+        nullable: true,
+        minLength: 1
+      }
+    }),
+    mode: "replace"
   });
 }
 

package/shared/validators/createCursorListValidator.test.js

@@ -1,34 +1,33 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { Type } from "typebox";
+import { createSchema } from "json-rest-schema";
 import { createCursorListValidator } from "./createCursorListValidator.js";
 
-test("createCursorListValidator builds a list validator from an item validator", () => {
+test("createCursorListValidator builds a list validator from a schema definition", () => {
   const itemValidator = {
-    schema: Type.Object(
-      {
-        id: Type.Integer({ minimum: 1 }),
-        label: Type.String({ minLength: 1 })
+    schema: createSchema({
+      id: {
+        type: "integer",
+        required: true,
+        min: 1
       },
-      { additionalProperties: false }
-    ),
-    normalize(payload = {}) {
-      return {
-        id: Number(payload.id),
-        label: String(payload.label || "").trim()
-      };
-    }
+      label: {
+        type: "string",
+        required: true,
+        minLength: 1
+      }
+    }),
+    mode: "replace"
   };
 
   const listValidator = createCursorListValidator(itemValidator);
-  const normalized = listValidator.normalize({
-    items: [{ id: "7", label: " member " }],
-    nextCursor: " 8 "
-  });
+  const transportSchema = listValidator.schema.toJsonSchema({ mode: listValidator.mode });
 
-  assert.deepEqual(normalized, {
-    items: [{ id: 7, label: "member" }],
-    nextCursor: "8"
-  });
-  assert.equal(listValidator.schema.properties.items.type, "array");
+  assert.equal(listValidator.mode, "replace");
+  assert.equal(transportSchema.properties.items.type, "array");
+  assert.equal(transportSchema.properties.items.items["x-json-rest-schema"]?.castType, "object");
+  assert.equal(Array.isArray(transportSchema.properties.items.items.allOf), true);
+  assert.match(transportSchema.properties.items.items.allOf[0]?.$ref || "", /^#\/definitions\//);
+  assert.equal(transportSchema.definitions.SchemaNode_1_replace.properties.label.type, "string");
+  assert.equal(transportSchema.definitions.SchemaNode_1_replace.properties.label.minLength, 1);
 });

package/shared/validators/cursorPaginationQueryValidator.js

@@ -1,31 +1,21 @@
-import { Type } from "typebox";
-import { normalizeObjectInput } from "./inputNormalization.js";
-import { positiveIntegerValidator, recordIdInputSchema, recordIdValidator } from "./recordIdParamsValidator.js";
+import { createSchema } from "json-rest-schema";
 
-function normalizeCursorPaginationQuery(input = {}) {
-  const source = normalizeObjectInput(input);
-  const normalized = {};
-
-  if (Object.hasOwn(source, "cursor")) {
-    normalized.cursor = recordIdValidator.normalize(source.cursor);
-  }
-
-  if (Object.hasOwn(source, "limit")) {
-    normalized.limit = positiveIntegerValidator.normalize(source.limit);
+const cursorPaginationQuerySchema = createSchema({
+  cursor: {
+    type: "id",
+    required: false
+  },
+  limit: {
+    type: "number",
+    required: false,
+    min: 1,
+    unsigned: true
   }
-
-  return normalized;
-}
+});
 
 const cursorPaginationQueryValidator = Object.freeze({
-  schema: Type.Object(
-    {
-      cursor: Type.Optional(recordIdInputSchema),
-      limit: Type.Optional(positiveIntegerValidator.schema)
-    },
-    { additionalProperties: false }
-  ),
-  normalize: normalizeCursorPaginationQuery
+  schema: cursorPaginationQuerySchema,
+  mode: "patch"
 });
 
 export {

package/shared/validators/cursorPaginationQueryValidator.test.js

@@ -1,26 +1,36 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { cursorPaginationQueryValidator } from "./cursorPaginationQueryValidator.js";
+import { validateSchemaPayload } from "./schemaPayloadValidation.js";
 
-test("cursorPaginationQueryValidator normalizes numeric strings as cursor text", () => {
-  assert.deepEqual(cursorPaginationQueryValidator.normalize({ cursor: "12", limit: "25" }), {
-    cursor: "12",
+test("cursorPaginationQueryValidator normalizes numeric strings through schema casting", () => {
+  assert.deepEqual(validateSchemaPayload(cursorPaginationQueryValidator, { cursor: "12", limit: "25" }), {
+    cursor: 12,
     limit: 25
   });
 });
 
 test("cursorPaginationQueryValidator schema rejects opaque cursor strings", () => {
+  const transportSchema = cursorPaginationQueryValidator.schema.toJsonSchema({ mode: "patch" });
   assert.equal(
-    cursorPaginationQueryValidator.schema.properties.cursor.type === "string" &&
-      cursorPaginationQueryValidator.schema.properties.cursor.pattern === "^[1-9][0-9]*$",
+    Array.isArray(transportSchema.properties.cursor.type) &&
+      transportSchema.properties.cursor.pattern === "^[1-9][0-9]*$",
     true
   );
 });
 
 test("cursorPaginationQueryValidator keeps absent keys absent", () => {
-  assert.deepEqual(cursorPaginationQueryValidator.normalize({}), {});
+  assert.deepEqual(validateSchemaPayload(cursorPaginationQueryValidator, {}), {});
 });
 
-test("cursorPaginationQueryValidator ignores unsupported query fields", () => {
-  assert.deepEqual(cursorPaginationQueryValidator.normalize({ q: "  to  " }), {});
+test("cursorPaginationQueryValidator rejects unsupported query fields", () => {
+  assert.throws(
+    () => validateSchemaPayload(cursorPaginationQueryValidator, { q: "  to  " }),
+    (error) => {
+      assert.deepEqual(error.fieldErrors, {
+        q: "Field not allowed"
+      });
+      return true;
+    }
+  );
 });

package/shared/validators/htmlTimeSchemas.js

@@ -1,11 +1,13 @@
-import { Type } from "typebox";
-
-const HTML_TIME_STRING_SCHEMA = Type.String({
+const HTML_TIME_STRING_SCHEMA = Object.freeze({
+  type: "string",
   pattern: "^(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d)?$",
   minLength: 5
 });
 
-const NULLABLE_HTML_TIME_STRING_SCHEMA = Type.Union([HTML_TIME_STRING_SCHEMA, Type.Null()]);
+const NULLABLE_HTML_TIME_STRING_SCHEMA = Object.freeze({
+  ...HTML_TIME_STRING_SCHEMA,
+  nullable: true
+});
 
 export {
   HTML_TIME_STRING_SCHEMA,

package/shared/validators/index.js

@@ -1,4 +1,6 @@
+export { createSchema } from "json-rest-schema";
 export { normalizeObjectInput } from "./inputNormalization.js";
+export { composeSchemaDefinitions } from "./composeSchemaDefinitions.js";
 export { createCursorListValidator } from "./createCursorListValidator.js";
 export { cursorPaginationQueryValidator } from "./cursorPaginationQueryValidator.js";
 export {
@@ -6,20 +8,26 @@ export {
   NULLABLE_HTML_TIME_STRING_SCHEMA
 } from "./htmlTimeSchemas.js";
 export { mergeObjectSchemas } from "./mergeObjectSchemas.js";
-export { mergeValidators } from "./mergeValidators.js";
-export { nestValidator } from "./nestValidator.js";
+export {
+  hasJsonRestSchemaDefinition,
+  normalizeSingleSchemaDefinition,
+  normalizeSchemaDefinition,
+  resolveSchemaTransportSchemaDefinition,
+  resolveStructuredSchemaTransportSchema,
+  executeJsonRestSchemaDefinition
+} from "./schemaDefinitions.js";
+export {
+  buildSchemaValidationError,
+  validateSchemaPayload
+} from "./schemaPayloadValidation.js";
 export {
   RECORD_ID_PATTERN,
   recordIdSchema,
   recordIdInputSchema,
   nullableRecordIdSchema,
   nullableRecordIdInputSchema,
-  recordIdValidator,
-  nullableRecordIdValidator,
-  recordIdParamsValidator,
-  positiveIntegerValidator
+  recordIdParamsValidator
 } from "./recordIdParamsValidator.js";
-export { normalizeSettingsFieldInput, normalizeSettingsFieldOutput } from "./settingsFieldNormalization.js";
 export {
   normalizeRequiredFieldList,
   deriveRequiredFieldsFromSchema,

package/shared/validators/jsonRestSchemaSupport.js

@@ -0,0 +1,139 @@
+import { normalizeObject, normalizeText } from "../support/normalize.js";
+
+const JSON_REST_SCHEMA_MODES = new Set(["create", "replace", "patch"]);
+const JSON_REST_SCHEMA_ERROR_MESSAGE_KEYS = Object.freeze({
+  REQUIRED: "required",
+  TYPE_CAST_FAILED: "default",
+  NOT_NULLABLE: "default",
+  MIN_LENGTH: "minLength",
+  MAX_LENGTH: "maxLength",
+  MIN_VALUE: "min",
+  MAX_VALUE: "max",
+  PATTERN: "pattern",
+  ENUM_VALUE: "enum",
+  FIELD_NOT_ALLOWED: "additionalProperties",
+  CUSTOM_VALIDATOR_FAILED: "default"
+});
+
+function isJsonRestSchemaInstance(value) {
+  return Boolean(value) &&
+    typeof value === "object" &&
+    typeof value.create === "function" &&
+    typeof value.replace === "function" &&
+    typeof value.patch === "function" &&
+    typeof value.toJsonSchema === "function";
+}
+
+function requireJsonRestSchemaInstance(schemaDefinition = null, {
+  context = "schema definition.schema"
+} = {}) {
+  const schema = normalizeObject(schemaDefinition).schema;
+  if (!isJsonRestSchemaInstance(schema)) {
+    throw new TypeError(`${context} must be a json-rest-schema schema instance.`);
+  }
+
+  return schema;
+}
+
+function resolveSchemaDefinitionMode(schemaDefinition = null, {
+  defaultMode = "create",
+  context = "schema definition.mode"
+} = {}) {
+  const source = normalizeObject(schemaDefinition);
+  const fallbackMode = normalizeText(defaultMode).toLowerCase() || "create";
+  const rawMode = Object.prototype.hasOwnProperty.call(source, "mode")
+    ? normalizeText(source.mode).toLowerCase()
+    : "";
+
+  if (!rawMode) {
+    return fallbackMode;
+  }
+
+  if (!JSON_REST_SCHEMA_MODES.has(rawMode)) {
+    throw new TypeError(`${context} must be one of: create, replace, patch.`);
+  }
+
+  return rawMode;
+}
+
+function resolveSchemaDefinitionTransportSchema(schemaDefinition = null, options = {}) {
+  const schema = requireJsonRestSchemaInstance(schemaDefinition, {
+    context: `${options?.context || "schema definition"}.schema`
+  });
+  const mode = resolveSchemaDefinitionMode(schemaDefinition, options);
+  return schema.toJsonSchema({ mode });
+}
+
+function executeSchemaDefinition(schemaDefinition = null, payload, options = {}) {
+  const schema = requireJsonRestSchemaInstance(schemaDefinition, {
+    context: `${options?.context || "schema definition"}.schema`
+  });
+  const mode = resolveSchemaDefinitionMode(schemaDefinition, options);
+  return schema[mode](payload);
+}
+
+function resolveJsonRestSchemaFieldMessages(schemaDefinition = null, fieldName = "") {
+  const normalizedFieldName = normalizeText(fieldName);
+  if (!normalizedFieldName) {
+    return {};
+  }
+
+  const source = normalizeObject(schemaDefinition);
+  if (!isJsonRestSchemaInstance(source.schema)) {
+    return {};
+  }
+
+  return normalizeObject(source.schema.getFieldMessages(normalizedFieldName));
+}
+
+function resolveJsonRestSchemaFieldErrorMessage(fieldName, entry, schemaDefinition = null) {
+  const messages = resolveJsonRestSchemaFieldMessages(schemaDefinition, fieldName);
+  const errorCode = normalizeText(entry?.code).toUpperCase();
+  const messageKey = JSON_REST_SCHEMA_ERROR_MESSAGE_KEYS[errorCode];
+
+  if (messageKey && typeof messages[messageKey] === "string") {
+    const overrideMessage = normalizeText(messages[messageKey]);
+    if (overrideMessage) {
+      return overrideMessage;
+    }
+  }
+
+  if (typeof messages.default === "string") {
+    const defaultMessage = normalizeText(messages.default);
+    if (defaultMessage) {
+      return defaultMessage;
+    }
+  }
+
+  return normalizeText(entry?.message || entry?.code || "Invalid value.");
+}
+
+function normalizeJsonRestSchemaFieldErrors(errors = {}, schemaDefinition = null) {
+  const source = normalizeObject(errors);
+  const fieldErrors = {};
+
+  for (const [fieldName, entry] of Object.entries(source)) {
+    const normalizedFieldName = normalizeText(fieldName);
+    if (!normalizedFieldName) {
+      continue;
+    }
+
+    if (typeof entry === "string") {
+      fieldErrors[normalizedFieldName] = entry;
+      continue;
+    }
+
+    const message = resolveJsonRestSchemaFieldErrorMessage(normalizedFieldName, entry, schemaDefinition);
+    fieldErrors[normalizedFieldName] = message || "Invalid value.";
+  }
+
+  return fieldErrors;
+}
+
+export {
+  isJsonRestSchemaInstance,
+  resolveSchemaDefinitionMode,
+  resolveSchemaDefinitionTransportSchema,
+  executeSchemaDefinition,
+  normalizeJsonRestSchemaFieldErrors
+};

package/shared/validators/mergeObjectSchemas.js

@@ -1,4 +1,31 @@
-import { Type } from "typebox";
+function cloneSchemaValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneSchemaValue(entry));
+  }
+
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [key, cloneSchemaValue(entry)])
+  );
+}
+
+function assertMergeableObjectSchema(schema) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new Error("mergeObjectSchemas only supports object schemas.");
+  }
+
+  const schemaType = schema.type;
+  if (schemaType !== "object") {
+    throw new Error("mergeObjectSchemas only supports object schemas.");
+  }
+
+  if (!schema.properties || typeof schema.properties !== "object" || Array.isArray(schema.properties)) {
+    throw new Error("mergeObjectSchemas only supports object schemas with properties.");
+  }
+}
 
 function mergeObjectSchemas(schemas) {
   if (!Array.isArray(schemas)) {
@@ -6,11 +33,10 @@ function mergeObjectSchemas(schemas) {
   }
 
   const mergedProperties = {};
+  const required = new Set();
 
   for (const schema of schemas) {
-    if (!schema || typeof schema !== "object" || schema.type !== "object" || typeof schema.properties !== "object") {
-      throw new Error("mergeObjectSchemas only supports Type.Object schemas.");
-    }
+    assertMergeableObjectSchema(schema);
 
     for (const [propertyName, propertySchema] of Object.entries(schema.properties)) {
       if (Object.hasOwn(mergedProperties, propertyName) && mergedProperties[propertyName] !== propertySchema) {
@@ -19,11 +45,23 @@ function mergeObjectSchemas(schemas) {
 
       mergedProperties[propertyName] = propertySchema;
     }
+
+    for (const propertyName of Array.isArray(schema.required) ? schema.required : []) {
+      required.add(propertyName);
+    }
   }
 
-  return Type.Object(mergedProperties, {
+  const mergedSchema = {
+    type: "object",
+    properties: mergedProperties,
     additionalProperties: false
-  });
+  };
+
+  if (required.size > 0) {
+    mergedSchema.required = [...required];
+  }
+
+  return cloneSchemaValue(mergedSchema);
 }
 
 export {