@modulify/validator 0.1.0 → 0.2.1

package/dist/json-schema.mjs

@@ -0,0 +1,514 @@
+import { d as describeConstraints } from "./metadata.es.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 = (metadata) => {
+  if (!metadata) {
+    return {};
+  }
+  const schemaMetadata = {};
+  jsonSchemaMetadataKeys.forEach((key) => {
+    if (!(key in metadata)) {
+      return;
+    }
+    const value = metadata[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, metadata) => {
+  const schemaMetadata = pickMetadata(metadata);
+  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 = describeConstraints(constraints);
+  const context = {
+    mode: options.mode ?? "bestEffort",
+    path: []
+  };
+  return exportDescriptor(descriptor, context);
+};
+export {
+  JsonSchemaExportError,
+  toJsonSchema
+};

package/dist/metadata.cjs

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const metadata = require("./metadata.cjs.js");
+exports.attachConstraintDescriptor = metadata.attachConstraintDescriptor;
+exports.custom = metadata.custom;
+exports.describe = metadata.describe;
+exports.describeConstraints = metadata.describeConstraints;
+exports.meta = metadata.meta;

package/dist/metadata.cjs.js

@@ -0,0 +1,130 @@
+"use strict";
+const isValidator = (constraint) => "run" in constraint;
+function arrayify(value) {
+  return Array.isArray(value) ? [...value] : [value];
+}
+function matchesConstraints(value, constraints) {
+  return arrayify(constraints).every((constraint) => constraint.check(value));
+}
+const constraintDescriptorSymbol = /* @__PURE__ */ Symbol("modulify.validator.descriptor");
+const constraintMetadataSymbol = /* @__PURE__ */ Symbol("modulify.validator.metadata");
+const cloneCallableConstraint = (constraint) => {
+  const source = constraint;
+  const cloned = ((value) => source(value));
+  const {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    length: _length,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    name: _name,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    prototype: _prototype,
+    ...descriptors
+  } = Object.getOwnPropertyDescriptors(source);
+  Object.defineProperties(cloned, descriptors);
+  try {
+    Object.defineProperty(cloned, "name", {
+      configurable: true,
+      value: source.name
+    });
+  } catch {
+  }
+  Object.setPrototypeOf(cloned, Object.getPrototypeOf(source));
+  return cloned;
+};
+const cloneConstraint = (constraint) => {
+  if (typeof constraint === "function") {
+    return cloneCallableConstraint(constraint);
+  }
+  return Object.create(
+    Object.getPrototypeOf(constraint),
+    Object.getOwnPropertyDescriptors(constraint)
+  );
+};
+const freezeMetadata = (metadata) => Object.freeze({ ...metadata });
+const getConstraintMetadata = (constraint) => {
+  return constraint[constraintMetadataSymbol];
+};
+const getDescriptorFactory = (constraint) => {
+  return constraint[constraintDescriptorSymbol];
+};
+const getPublicDescriptor = (constraint) => {
+  if (!isValidator(constraint)) {
+    return void 0;
+  }
+  const { describe: describe2 } = constraint;
+  return typeof describe2 === "function" ? describe2.call(constraint) : void 0;
+};
+const inferAssertionDescriptor = (assertion) => ({
+  kind: "assertion",
+  name: assertion.name,
+  bail: assertion.bail,
+  code: assertion.name,
+  args: [],
+  constraints: assertion.constraints.map(([, , code, ...args]) => ({
+    code,
+    args
+  }))
+});
+const withMetadata = (descriptor, metadata) => {
+  if (!metadata) {
+    return descriptor;
+  }
+  return {
+    ...descriptor,
+    metadata
+  };
+};
+const attachConstraintDescriptor = (constraint, describe2) => {
+  Object.defineProperty(constraint, constraintDescriptorSymbol, {
+    configurable: false,
+    enumerable: false,
+    value: describe2,
+    writable: false
+  });
+  return constraint;
+};
+const meta = (constraint, metadata) => {
+  const cloned = cloneConstraint(constraint);
+  const nextMetadata = freezeMetadata({
+    ...getConstraintMetadata(constraint) ?? {},
+    ...metadata
+  });
+  Object.defineProperty(cloned, constraintMetadataSymbol, {
+    configurable: true,
+    enumerable: false,
+    value: nextMetadata,
+    writable: false
+  });
+  return cloned;
+};
+const custom = (validator) => validator;
+const describeConstraints = (constraints) => {
+  const values = arrayify(constraints);
+  return values.length === 1 ? describe(values[0]) : {
+    kind: "allOf",
+    constraints: values.map((value) => describe(value))
+  };
+};
+const describe = (constraint) => {
+  const factory = getDescriptorFactory(constraint);
+  const metadata = getConstraintMetadata(constraint);
+  if (factory) {
+    return withMetadata(factory(), metadata);
+  }
+  const publicDescriptor = getPublicDescriptor(constraint);
+  if (publicDescriptor) {
+    return withMetadata(publicDescriptor, metadata);
+  }
+  if (isValidator(constraint)) {
+    return withMetadata({ kind: "validator" }, metadata);
+  }
+  return withMetadata(inferAssertionDescriptor(constraint), metadata);
+};
+exports.arrayify = arrayify;
+exports.attachConstraintDescriptor = attachConstraintDescriptor;
+exports.custom = custom;
+exports.describe = describe;
+exports.describeConstraints = describeConstraints;
+exports.isValidator = isValidator;
+exports.matchesConstraints = matchesConstraints;
+exports.meta = meta;

package/dist/metadata.d.ts

@@ -0,0 +1,8 @@
+import { Constraint, ConstraintDescriptor, ConstraintMetadata, DescribeConstraint, DescribeMaybeMany, MaybeMany, Validator } from '../types';
+type DescriptorFactory = () => ConstraintDescriptor;
+export declare const attachConstraintDescriptor: <C extends Constraint>(constraint: C, describe: DescriptorFactory) => C;
+export declare const meta: <const C extends Constraint, const M extends ConstraintMetadata>(constraint: C, metadata: M) => C;
+export declare const custom: <const V extends Validator>(validator: V) => V;
+export declare const describeConstraints: <const C extends MaybeMany<Constraint>>(constraints: C) => DescribeMaybeMany<C>;
+export declare const describe: <const C extends Constraint>(constraint: C) => DescribeConstraint<C>;
+export {};