@jskit-ai/kernel 0.1.4

package/shared/validators/createCursorListValidator.js

@@ -0,0 +1,42 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "./inputNormalization.js";
+import { normalizeText } from "../support/normalize.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);
+
+      return {
+        items: Array.isArray(source.items) ? source.items.map((entry) => normalizeItem(entry)) : [],
+        nextCursor: normalizeText(source.nextCursor) || null
+      };
+    }
+  });
+}
+
+export { createCursorListValidator };

package/shared/validators/createCursorListValidator.test.js

@@ -0,0 +1,34 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Type } from "typebox";
+import { createCursorListValidator } from "./createCursorListValidator.js";
+
+test("createCursorListValidator builds a list validator from an item validator", () => {
+  const itemValidator = {
+    schema: Type.Object(
+      {
+        id: Type.Integer({ minimum: 1 }),
+        label: Type.String({ minLength: 1 })
+      },
+      { additionalProperties: false }
+    ),
+    normalize(payload = {}) {
+      return {
+        id: Number(payload.id),
+        label: String(payload.label || "").trim()
+      };
+    }
+  };
+
+  const listValidator = createCursorListValidator(itemValidator);
+  const normalized = listValidator.normalize({
+    items: [{ id: "7", label: " member " }],
+    nextCursor: " 8 "
+  });
+
+  assert.deepEqual(normalized, {
+    items: [{ id: 7, label: "member" }],
+    nextCursor: "8"
+  });
+  assert.equal(listValidator.schema.properties.items.type, "array");
+});

package/shared/validators/cursorPaginationQueryValidator.js

@@ -0,0 +1,31 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "./inputNormalization.js";
+import { positiveIntegerValidator } from "./recordIdParamsValidator.js";
+
+function normalizeCursorPaginationQuery(input = {}) {
+  const source = normalizeObjectInput(input);
+  const normalized = {};
+
+  if (Object.hasOwn(source, "cursor")) {
+    normalized.cursor = positiveIntegerValidator.normalize(source.cursor);
+  }
+
+  if (Object.hasOwn(source, "limit")) {
+    normalized.limit = positiveIntegerValidator.normalize(source.limit);
+  }
+
+  return normalized;
+}
+
+const cursorPaginationQueryValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      cursor: Type.Optional(positiveIntegerValidator.schema),
+      limit: Type.Optional(positiveIntegerValidator.schema)
+    },
+    { additionalProperties: false }
+  ),
+  normalize: normalizeCursorPaginationQuery
+});
+
+export { cursorPaginationQueryValidator };

package/shared/validators/cursorPaginationQueryValidator.test.js

@@ -0,0 +1,21 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { cursorPaginationQueryValidator } from "./cursorPaginationQueryValidator.js";
+
+test("cursorPaginationQueryValidator normalizes numeric strings", () => {
+  assert.deepEqual(cursorPaginationQueryValidator.normalize({ cursor: "12", limit: "25" }), {
+    cursor: 12,
+    limit: 25
+  });
+});
+
+test("cursorPaginationQueryValidator normalizes invalid values to 0", () => {
+  assert.deepEqual(cursorPaginationQueryValidator.normalize({ cursor: "abc", limit: "-1" }), {
+    cursor: 0,
+    limit: 0
+  });
+});
+
+test("cursorPaginationQueryValidator keeps absent keys absent", () => {
+  assert.deepEqual(cursorPaginationQueryValidator.normalize({}), {});
+});

package/shared/validators/index.js

@@ -0,0 +1,12 @@
+export { normalizeObjectInput } from "./inputNormalization.js";
+export { createCursorListValidator } from "./createCursorListValidator.js";
+export { cursorPaginationQueryValidator } from "./cursorPaginationQueryValidator.js";
+export { mergeObjectSchemas } from "./mergeObjectSchemas.js";
+export { mergeValidators } from "./mergeValidators.js";
+export { nestValidator } from "./nestValidator.js";
+export { recordIdParamsValidator, positiveIntegerValidator } from "./recordIdParamsValidator.js";
+export {
+  normalizeRequiredFieldList,
+  deriveRequiredFieldsFromSchema,
+  deriveResourceRequiredMetadata
+} from "./resourceRequiredMetadata.js";

package/shared/validators/inputNormalization.js

@@ -0,0 +1,13 @@
+function normalizeObjectInput(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return {
+    ...value
+  };
+}
+
+export {
+  normalizeObjectInput
+};

package/shared/validators/mergeObjectSchemas.js

@@ -0,0 +1,31 @@
+import { Type } from "typebox";
+
+function mergeObjectSchemas(schemas) {
+  if (!Array.isArray(schemas)) {
+    throw new Error("mergeObjectSchemas requires an array of object schemas.");
+  }
+
+  const mergedProperties = {};
+
+  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.");
+    }
+
+    for (const [propertyName, propertySchema] of Object.entries(schema.properties)) {
+      if (Object.hasOwn(mergedProperties, propertyName) && mergedProperties[propertyName] !== propertySchema) {
+        throw new Error(`mergeObjectSchemas cannot merge duplicate property "${propertyName}".`);
+      }
+
+      mergedProperties[propertyName] = propertySchema;
+    }
+  }
+
+  return Type.Object(mergedProperties, {
+    additionalProperties: false
+  });
+}
+
+export {
+  mergeObjectSchemas
+};

package/shared/validators/mergeObjectSchemas.test.js

@@ -0,0 +1,67 @@
+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 }
+    )
+  ]);
+
+  assert.equal(mergedSchema.type, "object");
+  assert.equal(mergedSchema.additionalProperties, false);
+  assert.equal(typeof mergedSchema.properties.cursor, "object");
+  assert.equal(typeof mergedSchema.properties.search, "object");
+  assert.deepEqual(mergedSchema.required || [], []);
+});
+
+test("mergeObjectSchemas preserves required fields through merged property definitions", () => {
+  const mergedSchema = mergeObjectSchemas([
+    Type.Object(
+      {
+        workspaceSlug: Type.String({ minLength: 1 })
+      },
+      { additionalProperties: false }
+    ),
+    Type.Object(
+      {
+        inviteId: Type.String({ minLength: 1 })
+      },
+      { additionalProperties: false }
+    )
+  ]);
+
+  assert.deepEqual(mergedSchema.required, ["workspaceSlug", "inviteId"]);
+});
+
+test("mergeObjectSchemas rejects duplicate properties with different schema objects", () => {
+  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 }
+        )
+      ]),
+    /duplicate property "workspaceSlug"/
+  );
+});

package/shared/validators/mergeValidators.js

@@ -0,0 +1,89 @@
+import { mergeObjectSchemas } from "./mergeObjectSchemas.js";
+import { isRecord as isPlainObject } from "../support/normalize.js";
+
+function isPromiseLike(value) {
+  return Boolean(value) && typeof value.then === "function";
+}
+
+function createErrorFactory(createError) {
+  if (typeof createError === "function") {
+    return createError;
+  }
+
+  return (message) => new Error(message);
+}
+
+function mergeValidators(validators = [], options = {}) {
+  const sourceValidators = Array.isArray(validators) ? validators : [];
+  const context = String(options?.context || "validator").trim() || "validator";
+  const requireSchema = options?.requireSchema === true;
+  const allowAsyncNormalize = options?.allowAsyncNormalize !== false;
+  const requiredSchemaMessage = String(options?.requiredSchemaMessage || `${context}.schema is required.`);
+  const normalizeResultMessage = String(options?.normalizeResultMessage || `${context}.normalize must return an object.`);
+  const makeError = createErrorFactory(options?.createError);
+  const schemas = [];
+  const normalizers = [];
+
+  for (const validator of sourceValidators) {
+    if (!isPlainObject(validator)) {
+      continue;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(validator, "schema")) {
+      schemas.push(validator.schema);
+    }
+
+    if (typeof validator.normalize === "function") {
+      normalizers.push(validator.normalize);
+    }
+  }
+
+  if (requireSchema && schemas.length < 1) {
+    throw makeError(requiredSchemaMessage);
+  }
+
+  const merged = {};
+  if (schemas.length === 1) {
+    merged.schema = schemas[0];
+  } else if (schemas.length > 1) {
+    merged.schema = mergeObjectSchemas(schemas);
+  }
+
+  if (normalizers.length === 1) {
+    merged.normalize = normalizers[0];
+  } else if (normalizers.length > 1) {
+    if (allowAsyncNormalize) {
+      merged.normalize = async function normalizeMergedValidators(payload, meta) {
+        const normalized = {};
+
+        for (const normalizer of normalizers) {
+          const result = await normalizer(payload, meta);
+          if (!isPlainObject(result)) {
+            throw makeError(normalizeResultMessage);
+          }
+          Object.assign(normalized, result);
+        }
+
+        return normalized;
+      };
+    } else {
+      merged.normalize = function normalizeMergedValidators(payload, meta) {
+        const normalized = {};
+
+        for (const normalizer of normalizers) {
+          const result = normalizer(payload, meta);
+          if (isPromiseLike(result) || !isPlainObject(result)) {
+            throw makeError(normalizeResultMessage);
+          }
+          Object.assign(normalized, result);
+        }
+
+        return normalized;
+      };
+    }
+  }
+
+  return Object.freeze(merged);
+}
+
+export { mergeValidators };

package/shared/validators/mergeValidators.test.js

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "typebox";
+import { mergeValidators } from "./mergeValidators.js";
+
+test("mergeValidators merges schemas and sync normalizers", () => {
+  const merged = mergeValidators(
+    [
+      {
+        schema: Type.Object(
+          {
+            workspaceSlug: Type.Optional(Type.String({ minLength: 1 }))
+          },
+          { additionalProperties: false }
+        ),
+        normalize(input = {}) {
+          return {
+            workspaceSlug: String(input.workspaceSlug || "").trim().toLowerCase()
+          };
+        }
+      },
+      {
+        schema: Type.Object(
+          {
+            recordId: Type.Optional(Type.Union([Type.Integer({ minimum: 1 }), Type.String({ minLength: 1 })]))
+          },
+          { additionalProperties: false }
+        ),
+        normalize(input = {}) {
+          const parsed = Number(input.recordId);
+          return {
+            recordId: Number.isInteger(parsed) && parsed > 0 ? parsed : 0
+          };
+        }
+      }
+    ],
+    {
+      context: "route params",
+      allowAsyncNormalize: false
+    }
+  );
+
+  assert.equal(typeof merged.schema, "object");
+  assert.equal(typeof merged.normalize, "function");
+  assert.deepEqual(merged.normalize({ workspaceSlug: "  ACME  ", recordId: "42" }), {
+    workspaceSlug: "acme",
+    recordId: 42
+  });
+});
+
+test("mergeValidators merges async normalizers for action validators", async () => {
+  const merged = mergeValidators(
+    [
+      {
+        schema: Type.Object(
+          {
+            workspaceSlug: Type.Optional(Type.String({ minLength: 1 }))
+          },
+          { additionalProperties: false }
+        ),
+        async normalize(input = {}) {
+          return {
+            workspaceSlug: String(input.workspaceSlug || "").trim().toLowerCase()
+          };
+        }
+      },
+      {
+        schema: Type.Object(
+          {
+            invitesEnabled: Type.Optional(Type.Boolean())
+          },
+          { additionalProperties: false }
+        ),
+        normalize(input = {}) {
+          return {
+            invitesEnabled: input.invitesEnabled === true
+          };
+        }
+      }
+    ],
+    {
+      context: "action input"
+    }
+  );
+
+  assert.equal(typeof merged.schema, "object");
+  assert.equal(typeof merged.normalize, "function");
+  const normalized = await merged.normalize({
+    workspaceSlug: "  ACME  ",
+    invitesEnabled: true
+  });
+  assert.deepEqual(normalized, {
+    workspaceSlug: "acme",
+    invitesEnabled: true
+  });
+});
+
+test("mergeValidators enforces schema requirement when requested", () => {
+  assert.throws(
+    () =>
+      mergeValidators(
+        [
+          {
+            normalize() {
+              return {};
+            }
+          }
+        ],
+        {
+          context: "action input",
+          requireSchema: true
+        }
+      ),
+    /action input\.schema is required/
+  );
+});

package/shared/validators/nestValidator.js

@@ -0,0 +1,53 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "./inputNormalization.js";
+
+function normalizeValidator(validator) {
+  if (!validator || typeof validator !== "object" || Array.isArray(validator)) {
+    return null;
+  }
+
+  if (!Object.hasOwn(validator, "schema")) {
+    return null;
+  }
+
+  return validator;
+}
+
+function nestValidator(key, validator, { required = true } = {}) {
+  const normalizedKey = String(key || "").trim();
+  if (!normalizedKey) {
+    throw new TypeError("nestValidator requires a non-empty key.");
+  }
+
+  const normalizedValidator = normalizeValidator(validator);
+  if (!normalizedValidator) {
+    throw new TypeError(`nestValidator(\"${normalizedKey}\") requires a validator object with schema.`);
+  }
+
+  const keySchema = required ? normalizedValidator.schema : Type.Optional(normalizedValidator.schema);
+  const schema = Type.Object(
+    {
+      [normalizedKey]: keySchema
+    },
+    { additionalProperties: false }
+  );
+  const normalizeSection = typeof normalizedValidator.normalize === "function" ? normalizedValidator.normalize : null;
+
+  return Object.freeze({
+    schema,
+    async normalize(payload, meta) {
+      const source = normalizeObjectInput(payload);
+      if (!Object.hasOwn(source, normalizedKey)) {
+        return {};
+      }
+
+      const sectionPayload = source[normalizedKey];
+      const normalizedSection = normalizeSection ? await normalizeSection(sectionPayload, meta) : sectionPayload;
+      return {
+        [normalizedKey]: normalizedSection
+      };
+    }
+  });
+}
+
+export { nestValidator };

package/shared/validators/nestValidator.test.js

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Check } from "typebox/value";
+import { Type } from "typebox";
+import { nestValidator } from "./nestValidator.js";
+
+test("nestValidator wraps schema + normalize under one key", async () => {
+  const baseValidator = Object.freeze({
+    schema: Type.Object(
+      {
+        name: Type.Optional(Type.String({ minLength: 1 }))
+      },
+      { additionalProperties: false }
+    ),
+    normalize(payload = {}) {
+      return {
+        ...(Object.hasOwn(payload, "name") ? { name: String(payload.name).trim() } : {})
+      };
+    }
+  });
+  const validator = nestValidator("payload", baseValidator);
+
+  const normalized = await validator.normalize({
+    payload: {
+      name: "  Acme  "
+    }
+  });
+
+  assert.deepEqual(normalized, {
+    payload: {
+      name: "Acme"
+    }
+  });
+  assert.equal(Check(validator.schema, normalized), true);
+  assert.equal(Check(validator.schema, {}), false);
+});
+
+test("nestValidator can define optional nested key", async () => {
+  const validator = nestValidator(
+    "patch",
+    Object.freeze({
+      schema: Type.Object(
+        {
+          title: Type.Optional(Type.String({ minLength: 1 }))
+        },
+        { additionalProperties: false }
+      )
+    }),
+    { required: false }
+  );
+
+  assert.deepEqual(await validator.normalize({}), {});
+  assert.equal(Check(validator.schema, {}), true);
+  assert.equal(Check(validator.schema, { patch: { title: "X" } }), true);
+});
+
+test("nestValidator rejects invalid key and validator", () => {
+  assert.throws(() => nestValidator("", { schema: Type.Object({}) }), /requires a non-empty key/);
+  assert.throws(() => nestValidator("payload", null), /requires a validator object with schema/);
+});

package/shared/validators/recordIdParamsValidator.js

@@ -0,0 +1,36 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "./inputNormalization.js";
+import { normalizePositiveInteger, normalizeText } from "../support/normalize.js";
+
+function normalizeRecordId(value) {
+  return normalizePositiveInteger(normalizeText(value));
+}
+
+const positiveIntegerValidator = Object.freeze({
+  schema: Type.Union([
+    Type.Integer({ minimum: 1 }),
+    Type.String({ minLength: 1, pattern: "^[1-9][0-9]*$" })
+  ]),
+  normalize: normalizeRecordId
+});
+
+const recordIdParamsValidator = Object.freeze({
+  schema: Type.Object(
+    {
+      recordId: Type.Optional(positiveIntegerValidator.schema)
+    },
+    { additionalProperties: false }
+  ),
+  normalize(input = {}) {
+    const source = normalizeObjectInput(input);
+    const normalized = {};
+
+    if (Object.hasOwn(source, "recordId")) {
+      normalized.recordId = normalizeRecordId(source.recordId);
+    }
+
+    return normalized;
+  }
+});
+
+export { recordIdParamsValidator, positiveIntegerValidator };

package/shared/validators/recordIdParamsValidator.test.js

@@ -0,0 +1,20 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { recordIdParamsValidator } from "./recordIdParamsValidator.js";
+
+test("recordIdParamsValidator normalizes string id to positive integer", () => {
+  assert.deepEqual(recordIdParamsValidator.normalize({ recordId: "42" }), {
+    recordId: 42
+  });
+});
+
+test("recordIdParamsValidator normalizes invalid id to 0", () => {
+  assert.deepEqual(recordIdParamsValidator.normalize({ recordId: "nope" }), {
+    recordId: 0
+  });
+});
+
+test("recordIdParamsValidator keeps absent key absent", () => {
+  assert.deepEqual(recordIdParamsValidator.normalize({}), {});
+});

package/shared/validators/resourceRequiredMetadata.js

@@ -0,0 +1,41 @@
+function normalizeRequiredFieldList(value) {
+  if (!Array.isArray(value)) {
+    return Object.freeze([]);
+  }
+
+  const normalized = value
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+
+  return Object.freeze(Array.from(new Set(normalized)));
+}
+
+function deriveRequiredFieldsFromSchema(schema) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return Object.freeze([]);
+  }
+
+  return normalizeRequiredFieldList(schema.required);
+}
+
+function deriveResourceRequiredMetadata(resourceSchema) {
+  const operations = resourceSchema && typeof resourceSchema === "object"
+    ? resourceSchema.operations
+    : null;
+
+  const createSchema = operations?.create?.bodyValidator?.schema;
+  const replaceSchema = operations?.replace?.bodyValidator?.schema;
+  const patchSchema = operations?.patch?.bodyValidator?.schema;
+
+  return Object.freeze({
+    create: deriveRequiredFieldsFromSchema(createSchema),
+    replace: deriveRequiredFieldsFromSchema(replaceSchema),
+    patch: deriveRequiredFieldsFromSchema(patchSchema)
+  });
+}
+
+export {
+  normalizeRequiredFieldList,
+  deriveRequiredFieldsFromSchema,
+  deriveResourceRequiredMetadata
+};