@modulify/validator 0.1.0 → 0.2.0

package/dist/json-schema.cjs

@@ -0,0 +1,514 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const metadata = require("./metadata.cjs.js");
+const jsonSchemaMetadataKeys = [
+  "title",
+  "description",
+  "format",
+  "default",
+  "examples",
+  "deprecated",
+  "readOnly",
+  "writeOnly"
+];
+const typeOf = (value) => Object.prototype.toString.call(value);
+const isEmptySchema = (schema) => Object.keys(schema).length === 0;
+const isFiniteJsonNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const isJsonScalar = (value) => {
+  return value === null || typeof value === "string" || typeof value === "boolean" || isFiniteJsonNumber(value);
+};
+const isLength = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const isPositiveFiniteNumber = (value) => isFiniteNumber(value) && value > 0;
+const withPath = (context, segment) => ({
+  ...context,
+  path: [...context.path, segment]
+});
+const formatPath = (path) => path.length === 0 ? "<root>" : path.map((segment) => typeof segment === "symbol" ? segment.toString() : String(segment)).join(".");
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const setSchemaProperty = (schema, key, value) => {
+  schema[key] = value;
+};
+const pickMetadata = (metadata2) => {
+  if (!metadata2) {
+    return {};
+  }
+  const schemaMetadata = {};
+  jsonSchemaMetadataKeys.forEach((key) => {
+    if (!(key in metadata2)) {
+      return;
+    }
+    const value = metadata2[key];
+    if (key === "examples") {
+      if (Array.isArray(value)) {
+        setSchemaProperty(schemaMetadata, "examples", [...value]);
+      }
+      return;
+    }
+    if (key === "default") {
+      setSchemaProperty(schemaMetadata, "default", value);
+      return;
+    }
+    if ((key === "deprecated" || key === "readOnly" || key === "writeOnly") && typeof value === "boolean") {
+      setSchemaProperty(schemaMetadata, key, value);
+      return;
+    }
+    if (typeof value === "string") {
+      setSchemaProperty(schemaMetadata, key, value);
+    }
+  });
+  return schemaMetadata;
+};
+const applyMetadata = (schema, metadata2) => {
+  const schemaMetadata = pickMetadata(metadata2);
+  const nextSchema = { ...schema };
+  jsonSchemaMetadataKeys.forEach((key) => {
+    if (!(key in schemaMetadata) || key in nextSchema) {
+      return;
+    }
+    setSchemaProperty(nextSchema, key, schemaMetadata[key]);
+  });
+  return nextSchema;
+};
+class JsonSchemaExportError extends Error {
+  constructor(message, {
+    descriptor,
+    path = [],
+    reason
+  }) {
+    super(message);
+    this.name = "JsonSchemaExportError";
+    this.descriptor = descriptor;
+    this.reason = reason;
+    this.path = [...path];
+  }
+}
+const unsupported = (descriptor, context, reason) => {
+  if (context.mode === "strict") {
+    throw new JsonSchemaExportError(
+      `Cannot export ${descriptor.kind} at ${formatPath(context.path)}: ${reason}`,
+      { descriptor, path: context.path, reason }
+    );
+  }
+  return {};
+};
+const mergeNullable = (schema) => {
+  if (isEmptySchema(schema)) {
+    return schema;
+  }
+  return {
+    anyOf: [schema, { type: "null" }]
+  };
+};
+const toPropertyName = (key, descriptor, context) => {
+  if (typeof key === "symbol") {
+    return unsupported(descriptor, context, "symbol keys cannot be represented in JSON Schema");
+  }
+  return String(key);
+};
+const lengthSchema = (descriptor, context) => {
+  const stringSchema2 = { type: "string" };
+  const arraySchema = { type: "array" };
+  for (const constraint of descriptor.constraints) {
+    switch (constraint.code) {
+      case "length.exact": {
+        const exact = constraint.args[0];
+        if (!isLength(exact)) {
+          return unsupported(descriptor, context, "hasLength exact bounds must be non-negative integers");
+        }
+        setSchemaProperty(stringSchema2, "minLength", exact);
+        setSchemaProperty(stringSchema2, "maxLength", exact);
+        setSchemaProperty(arraySchema, "minItems", exact);
+        setSchemaProperty(arraySchema, "maxItems", exact);
+        break;
+      }
+      case "length.min": {
+        const min = constraint.args[0];
+        if (!isLength(min)) {
+          return unsupported(descriptor, context, "hasLength minimum bounds must be non-negative integers");
+        }
+        setSchemaProperty(stringSchema2, "minLength", min);
+        setSchemaProperty(arraySchema, "minItems", min);
+        break;
+      }
+      case "length.max": {
+        const max = constraint.args[0];
+        if (!isLength(max)) {
+          return unsupported(descriptor, context, "hasLength maximum bounds must be non-negative integers");
+        }
+        setSchemaProperty(stringSchema2, "maxLength", max);
+        setSchemaProperty(arraySchema, "maxItems", max);
+        break;
+      }
+      case "length.range": {
+        const range = constraint.args[0];
+        if (!Array.isArray(range) || range.length !== 2 || !isLength(range[0]) || !isLength(range[1])) {
+          return unsupported(descriptor, context, "hasLength ranges must be `[min, max]` integer tuples");
+        }
+        setSchemaProperty(stringSchema2, "minLength", range[0]);
+        setSchemaProperty(stringSchema2, "maxLength", range[1]);
+        setSchemaProperty(arraySchema, "minItems", range[0]);
+        setSchemaProperty(arraySchema, "maxItems", range[1]);
+        break;
+      }
+      default:
+        return unsupported(descriptor, context, `unsupported hasLength constraint "${constraint.code}"`);
+    }
+  }
+  return {
+    anyOf: [stringSchema2, arraySchema]
+  };
+};
+const exactSchema = (descriptor, context) => {
+  const [value] = descriptor.args ?? [];
+  if (!isJsonScalar(value)) {
+    return unsupported(
+      descriptor,
+      context,
+      `exact(...) supports only JSON scalar values, got ${typeOf(value)}`
+    );
+  }
+  return { const: value };
+};
+const enumSchema = (descriptor, context) => {
+  const [values] = descriptor.args ?? [];
+  if (!Array.isArray(values) || values.some((value) => !isJsonScalar(value))) {
+    return unsupported(
+      descriptor,
+      context,
+      "oneOf(...) supports only arrays of JSON scalar values"
+    );
+  }
+  return { enum: [...new Set(values)] };
+};
+const stringSchema = (descriptor, context) => {
+  if (descriptor.name === "hasPattern") {
+    const [pattern] = descriptor.constraints[0]?.args ?? [];
+    if (!(pattern instanceof RegExp)) {
+      return unsupported(descriptor, context, "hasPattern(...) requires a RegExp pattern");
+    }
+    if (pattern.flags !== "") {
+      return unsupported(descriptor, context, "hasPattern(...) supports only flagless regular expressions in JSON Schema");
+    }
+    return {
+      type: "string",
+      pattern: pattern.source
+    };
+  }
+  if (descriptor.name === "startsWith") {
+    const [prefix] = descriptor.constraints[0]?.args ?? [];
+    if (typeof prefix !== "string") {
+      return unsupported(descriptor, context, "startsWith(...) requires a string prefix");
+    }
+    return {
+      type: "string",
+      pattern: `^${escapeRegExp(prefix)}`
+    };
+  }
+  const [suffix] = descriptor.constraints[0]?.args ?? [];
+  if (typeof suffix !== "string") {
+    return unsupported(descriptor, context, "endsWith(...) requires a string suffix");
+  }
+  return {
+    type: "string",
+    pattern: `${escapeRegExp(suffix)}$`
+  };
+};
+const numberSchema = (descriptor, context) => {
+  const schema = { type: "number" };
+  if (descriptor.name === "multipleOf") {
+    const [step] = descriptor.constraints[0]?.args ?? [];
+    if (!isPositiveFiniteNumber(step)) {
+      return unsupported(descriptor, context, "multipleOf(...) requires a positive finite divisor");
+    }
+    setSchemaProperty(schema, "multipleOf", step);
+    return schema;
+  }
+  for (const constraint of descriptor.constraints) {
+    switch (constraint.code) {
+      case "number.exact": {
+        const exact = constraint.args[0];
+        if (!isFiniteNumber(exact)) {
+          return unsupported(descriptor, context, "hasValue exact bounds must be finite numbers");
+        }
+        setSchemaProperty(schema, "const", exact);
+        break;
+      }
+      case "number.min": {
+        const min = constraint.args[0];
+        if (!isFiniteNumber(min)) {
+          return unsupported(descriptor, context, "hasValue minimum bounds must be finite numbers");
+        }
+        setSchemaProperty(schema, "minimum", min);
+        break;
+      }
+      case "number.max": {
+        const max = constraint.args[0];
+        if (!isFiniteNumber(max)) {
+          return unsupported(descriptor, context, "hasValue maximum bounds must be finite numbers");
+        }
+        setSchemaProperty(schema, "maximum", max);
+        break;
+      }
+      case "number.range": {
+        const range = constraint.args[0];
+        if (!Array.isArray(range) || range.length !== 2 || !isFiniteNumber(range[0]) || !isFiniteNumber(range[1])) {
+          return unsupported(descriptor, context, "hasValue ranges must be `[min, max]` finite number tuples");
+        }
+        setSchemaProperty(schema, "minimum", range[0]);
+        setSchemaProperty(schema, "maximum", range[1]);
+        break;
+      }
+      default:
+        return unsupported(descriptor, context, `unsupported number assertion "${descriptor.name}"`);
+    }
+  }
+  return schema;
+};
+const assertionAcceptsUndefined = (descriptor) => {
+  switch (descriptor.name) {
+    case "exact":
+      return descriptor.args?.[0] === void 0;
+    case "oneOf": {
+      const [values] = descriptor.args ?? [];
+      return Array.isArray(values) && values.includes(void 0);
+    }
+    default:
+      return false;
+  }
+};
+const acceptsUndefined = (descriptor) => {
+  switch (descriptor.kind) {
+    case "optional":
+    case "nullish":
+      return true;
+    case "nullable":
+    case "each":
+    case "tuple":
+    case "record":
+    case "shape":
+    case "discriminatedUnion":
+    case "validator":
+      return false;
+    case "allOf":
+      return descriptor.constraints.every(acceptsUndefined);
+    case "union":
+      return descriptor.branches.some(acceptsUndefined);
+    case "assertion":
+      return assertionAcceptsUndefined(descriptor);
+    default:
+      return false;
+  }
+};
+const exportShapeRules = (descriptor, context) => {
+  if (descriptor.rules.length === 0 || context.mode === "bestEffort") {
+    return;
+  }
+  const [rule] = descriptor.rules;
+  throw new JsonSchemaExportError(
+    `Cannot export shape at ${formatPath([...context.path, "rules"])}: object-level rule "${rule.kind}" has no JSON Schema mapping`,
+    {
+      descriptor,
+      path: [...context.path, "rules"],
+      reason: `object-level rule "${rule.kind}" has no JSON Schema mapping`
+    }
+  );
+};
+const exportAssertion = (descriptor, context) => {
+  switch (descriptor.name) {
+    case "isString":
+      return { type: "string" };
+    case "isNumber":
+      return { type: "number" };
+    case "isBoolean":
+      return { type: "boolean" };
+    case "isBigInt":
+      return unsupported(descriptor, context, "bigint values cannot be represented in JSON Schema");
+    case "isBlob":
+      return unsupported(descriptor, context, "Blob instances do not have a stable JSON Schema representation");
+    case "isNull":
+      return { type: "null" };
+    case "isEmail":
+      return {
+        type: "string",
+        format: "email"
+      };
+    case "hasPattern":
+    case "startsWith":
+    case "endsWith":
+      return stringSchema(descriptor, context);
+    case "isFile":
+      return unsupported(descriptor, context, "File instances do not have a stable JSON Schema representation");
+    case "isFunction":
+      return unsupported(descriptor, context, "functions cannot be represented in JSON Schema");
+    case "isDefined":
+      return {};
+    case "isMap":
+      return unsupported(descriptor, context, "Map instances do not have a stable JSON Schema representation");
+    case "isNaN":
+      return unsupported(descriptor, context, "NaN cannot be represented in JSON Schema");
+    case "hasValue":
+    case "multipleOf":
+      return numberSchema(descriptor, context);
+    case "exact":
+      return exactSchema(descriptor, context);
+    case "hasSize":
+      return unsupported(descriptor, context, "Map and Set sizes do not have a stable JSON Schema representation");
+    case "oneOf":
+      return enumSchema(descriptor, context);
+    case "hasLength":
+      return lengthSchema(descriptor, context);
+    case "isDate":
+      return unsupported(descriptor, context, "Date instances do not have a stable JSON Schema representation");
+    case "isSet":
+      return unsupported(descriptor, context, "Set instances do not have a stable JSON Schema representation");
+    case "isSymbol":
+      return unsupported(descriptor, context, "symbols cannot be represented in JSON Schema");
+    default:
+      return unsupported(descriptor, context, `unsupported assertion "${descriptor.name}"`);
+  }
+};
+const exportDiscriminatedUnion = (descriptor, context) => {
+  if (typeof descriptor.key === "symbol") {
+    return unsupported(descriptor, context, "symbol discriminators cannot be represented in JSON Schema");
+  }
+  const key = String(descriptor.key);
+  const variants = descriptor.variants;
+  const branches = Reflect.ownKeys(variants).map((variantKey) => {
+    if (typeof variantKey === "symbol") {
+      return unsupported(descriptor, withPath(context, variantKey), "symbol discriminator values cannot be represented in JSON Schema");
+    }
+    const variant = variants[variantKey];
+    const branch = exportDescriptor(variant, withPath(context, variantKey));
+    return {
+      allOf: [{
+        type: "object",
+        properties: {
+          [key]: {
+            const: variantKey
+          }
+        },
+        required: [key]
+      }, branch]
+    };
+  });
+  return {
+    oneOf: branches
+  };
+};
+const exportRulesAsComment = (rules, schema) => ({
+  ...schema,
+  $comment: `Dropped ${rules.length} object rule(s) during best-effort JSON Schema export.`
+});
+const exportDescriptor = (descriptor, context) => {
+  let schema;
+  switch (descriptor.kind) {
+    case "assertion":
+      schema = exportAssertion(descriptor, context);
+      break;
+    case "allOf": {
+      const allOfDescriptor = descriptor;
+      schema = {
+        allOf: allOfDescriptor.constraints.map((child, index) => exportDescriptor(child, withPath(context, index)))
+      };
+      break;
+    }
+    case "optional": {
+      const wrapperDescriptor = descriptor;
+      schema = exportDescriptor(wrapperDescriptor.child, withPath(context, "optional"));
+      break;
+    }
+    case "nullable":
+    case "nullish": {
+      const wrapperDescriptor = descriptor;
+      schema = mergeNullable(exportDescriptor(wrapperDescriptor.child, withPath(context, descriptor.kind)));
+      break;
+    }
+    case "each": {
+      const eachDescriptor = descriptor;
+      schema = {
+        type: "array",
+        items: exportDescriptor(eachDescriptor.item, withPath(context, "items"))
+      };
+      break;
+    }
+    case "tuple": {
+      const tupleDescriptor = descriptor;
+      schema = {
+        type: "array",
+        prefixItems: tupleDescriptor.items.map((item, index) => exportDescriptor(item, withPath(context, index))),
+        minItems: tupleDescriptor.items.length,
+        maxItems: tupleDescriptor.items.length
+      };
+      break;
+    }
+    case "union": {
+      const unionDescriptor = descriptor;
+      schema = {
+        anyOf: unionDescriptor.branches.map((branch, index) => exportDescriptor(branch, withPath(context, index)))
+      };
+      break;
+    }
+    case "record": {
+      const recordDescriptor = descriptor;
+      schema = {
+        type: "object",
+        additionalProperties: exportDescriptor(recordDescriptor.values, withPath(context, "additionalProperties"))
+      };
+      break;
+    }
+    case "shape": {
+      const shapeDescriptor = descriptor;
+      const fields = shapeDescriptor.fields;
+      const rules = shapeDescriptor.rules;
+      exportShapeRules(shapeDescriptor, context);
+      const properties = {};
+      const required = [];
+      Reflect.ownKeys(fields).forEach((key) => {
+        const childContext = withPath(context, key);
+        const propertyName = toPropertyName(key, shapeDescriptor, childContext);
+        if (typeof propertyName !== "string") {
+          return;
+        }
+        const child = fields[key];
+        properties[propertyName] = exportDescriptor(child, childContext);
+        if (!acceptsUndefined(child)) {
+          required.push(propertyName);
+        }
+      });
+      const shapeSchema = {
+        type: "object",
+        properties,
+        additionalProperties: shapeDescriptor.unknownKeys === "strict" ? false : true
+      };
+      if (required.length > 0) {
+        setSchemaProperty(shapeSchema, "required", required);
+      }
+      schema = shapeSchema;
+      if (rules.length > 0 && context.mode === "bestEffort") {
+        schema = exportRulesAsComment(rules, schema);
+      }
+      break;
+    }
+    case "discriminatedUnion":
+      schema = exportDiscriminatedUnion(descriptor, context);
+      break;
+    case "validator":
+      schema = unsupported(descriptor, context, "custom validators need a supported public descriptor");
+      break;
+    default:
+      schema = unsupported(descriptor, context, `unsupported descriptor kind "${descriptor.kind}"`);
+      break;
+  }
+  return applyMetadata(schema, descriptor.metadata);
+};
+const toJsonSchema = (constraints, options = {}) => {
+  const descriptor = metadata.describeConstraints(constraints);
+  const context = {
+    mode: options.mode ?? "bestEffort",
+    path: []
+  };
+  return exportDescriptor(descriptor, context);
+};
+exports.JsonSchemaExportError = JsonSchemaExportError;
+exports.toJsonSchema = toJsonSchema;

package/dist/json-schema.d.ts

@@ -0,0 +1,14 @@
+import { Constraint, ConstraintDescriptor, MaybeMany } from '../types';
+import { JsonSchema, ToJsonSchemaOptions } from '../types/json-schema';
+export type { JsonSchema, JsonSchemaExportMode, JsonSchemaTypeName, ToJsonSchemaOptions, } from '../types/json-schema';
+export declare class JsonSchemaExportError extends Error {
+    readonly descriptor: ConstraintDescriptor;
+    readonly reason: string;
+    readonly path: readonly PropertyKey[];
+    constructor(message: string, { descriptor, path, reason, }: {
+        descriptor: ConstraintDescriptor;
+        reason: string;
+        path?: readonly PropertyKey[];
+    });
+}
+export declare const toJsonSchema: <const C extends MaybeMany<Constraint>>(constraints: C, options?: ToJsonSchemaOptions) => JsonSchema;