@formspec/validator 0.1.0-alpha.12

package/README.md

@@ -0,0 +1,95 @@
+# @formspec/validator
+
+JSON Schema validation for FormSpec, powered by [@cfworker/json-schema](https://github.com/nicolo-ribaudo/cfworker-json-schema). Designed for secure runtime environments that prohibit `new Function()` and `eval()`.
+
+## Installation
+
+```bash
+npm install @formspec/validator
+# or
+pnpm add @formspec/validator
+```
+
+## Requirements
+
+This package is ESM-only and requires:
+
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  }
+}
+```
+
+## Quick Start
+
+```typescript
+import { createFormSpecValidator } from "@formspec/validator";
+import { buildFormSchemas, formspec, field } from "formspec";
+
+const form = formspec(
+  field.text("name", { required: true }),
+  field.number("age", { min: 0 })
+);
+
+const { jsonSchema } = buildFormSchemas(form);
+
+// Create a validator that ignores x-formspec-* extension keywords
+const validator = createFormSpecValidator(jsonSchema);
+
+const result = validator.validate({ name: "Alice", age: 30 });
+console.log(result.valid); // true
+```
+
+## Why This Package?
+
+Standard JSON Schema validators like Ajv use `new Function()` internally, which is blocked in:
+
+- Cloudflare Workers
+- Deno Deploy
+- Browser extensions (CSP restrictions)
+- Any environment with strict Content Security Policy
+
+`@formspec/validator` wraps `@cfworker/json-schema`, which implements JSON Schema validation without code generation. It also pre-configures the validator to silently ignore `x-formspec-*` vendor extension keywords that FormSpec adds to generated schemas.
+
+## API Reference
+
+### Functions
+
+| Function | Description |
+| --- | --- |
+| `createFormSpecValidator(schema, options?)` | Create a validator instance for a JSON Schema |
+
+### Options
+
+```typescript
+interface CreateValidatorOptions {
+  draft?: SchemaDraft;    // JSON Schema draft version (default: "2020-12")
+  shortCircuit?: boolean; // Stop on first error (default: true)
+}
+```
+
+### Re-exports
+
+This package re-exports key types from `@cfworker/json-schema`:
+
+| Export | Description |
+| --- | --- |
+| `Validator` | The validator class |
+| `ValidationResult` | Result of `validator.validate()` |
+| `OutputUnit` | Individual validation error detail |
+| `SchemaDraft` | Supported JSON Schema draft versions |
+
+## License
+
+UNLICENSED

package/dist/__tests__/validator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validator.test.d.ts.map

package/dist/__tests__/validator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/validator.test.ts"],"names":[],"mappings":""}

package/dist/index.cjs

@@ -0,0 +1,38 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Validator: () => import_json_schema.Validator,
+  createFormSpecValidator: () => createFormSpecValidator
+});
+module.exports = __toCommonJS(index_exports);
+var import_json_schema = require("@cfworker/json-schema");
+function createFormSpecValidator(schema, options) {
+  const draft = options?.draft ?? "2020-12";
+  const shortCircuit = options?.shortCircuit ?? true;
+  return new import_json_schema.Validator(schema, draft, shortCircuit);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Validator,
+  createFormSpecValidator
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@formspec/validator` — JSON Schema validator for FormSpec\n *\n * Backed by {@link https://github.com/cfworker/cfworker/tree/main/packages/json-schema | @cfworker/json-schema},\n * this package validates data against FormSpec-generated JSON Schemas in any\n * JavaScript runtime — including secure environments that disallow `new Function()`\n * (e.g., Cloudflare Workers).\n *\n * Unlike Ajv, `@cfworker/json-schema` silently ignores unknown keywords, so\n * FormSpec's `x-formspec-*` extension keywords require no vocabulary registration.\n *\n * @example\n * ```typescript\n * import { createFormSpecValidator } from \"@formspec/validator\";\n *\n * const validator = createFormSpecValidator({\n *   type: \"object\",\n *   required: [\"name\"],\n *   properties: {\n *     name: { type: \"string\" },\n *     country: { type: \"string\", \"x-formspec-source\": \"countries\" },\n *   },\n * });\n *\n * const result = validator.validate({ name: \"Alice\", country: \"US\" });\n * // result.valid === true\n * ```\n *\n * @packageDocumentation\n */\n\nimport { Validator } from \"@cfworker/json-schema\";\nimport type { OutputUnit, Schema, SchemaDraft, ValidationResult } from \"@cfworker/json-schema\";\n\nexport { Validator };\nexport type { OutputUnit, SchemaDraft, ValidationResult };\n\n/**\n * Options for `createFormSpecValidator`.\n *\n * @public\n */\nexport interface CreateValidatorOptions {\n  /**\n   * The JSON Schema draft version to validate against.\n   *\n   * FormSpec generates schemas targeting JSON Schema 2020-12.\n   *\n   * @defaultValue `\"2020-12\"`\n   */\n  draft?: SchemaDraft;\n\n  /**\n   * When `true`, validation stops after the first error.\n   * When `false`, all errors are collected.\n   *\n   * @defaultValue `true`\n   */\n  shortCircuit?: boolean;\n}\n\n/**\n * Creates a `Validator` configured for FormSpec-generated JSON Schemas.\n *\n * The returned `Validator` uses JSON Schema draft 2020-12 by default and\n * silently ignores `x-formspec-*` extension keywords — no vocabulary\n * registration is needed.\n *\n * @param schema - A JSON Schema object (typically generated by `@formspec/build`).\n * @param options - Optional configuration for draft version and error collection behavior.\n * @returns A `Validator` instance whose `validate()` method returns a `ValidationResult`.\n *\n * @public\n */\nexport function createFormSpecValidator(\n  schema: Record<string, unknown>,\n  options?: CreateValidatorOptions,\n): Validator {\n  const draft = options?.draft ?? \"2020-12\";\n  const shortCircuit = options?.shortCircuit ?? true;\n  // Safe cast: Schema has `[key: string]: any`, so every Record<string, unknown>\n  // structurally satisfies it. We keep the public parameter as Record<string, unknown>\n  // to avoid coupling consumers to @cfworker/json-schema's Schema type.\n  return new Validator(schema as Schema, draft, shortCircuit);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+BA,yBAA0B;AA2CnB,SAAS,wBACd,QACA,SACW;AACX,QAAM,QAAQ,SAAS,SAAS;AAChC,QAAM,eAAe,SAAS,gBAAgB;AAI9C,SAAO,IAAI,6BAAU,QAAkB,OAAO,YAAY;AAC5D;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `@formspec/validator` — JSON Schema validator for FormSpec
+ *
+ * Backed by {@link https://github.com/cfworker/cfworker/tree/main/packages/json-schema | @cfworker/json-schema},
+ * this package validates data against FormSpec-generated JSON Schemas in any
+ * JavaScript runtime — including secure environments that disallow `new Function()`
+ * (e.g., Cloudflare Workers).
+ *
+ * Unlike Ajv, `@cfworker/json-schema` silently ignores unknown keywords, so
+ * FormSpec's `x-formspec-*` extension keywords require no vocabulary registration.
+ *
+ * @example
+ * ```typescript
+ * import { createFormSpecValidator } from "@formspec/validator";
+ *
+ * const validator = createFormSpecValidator({
+ *   type: "object",
+ *   required: ["name"],
+ *   properties: {
+ *     name: { type: "string" },
+ *     country: { type: "string", "x-formspec-source": "countries" },
+ *   },
+ * });
+ *
+ * const result = validator.validate({ name: "Alice", country: "US" });
+ * // result.valid === true
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { Validator } from "@cfworker/json-schema";
+import type { OutputUnit, SchemaDraft, ValidationResult } from "@cfworker/json-schema";
+export { Validator };
+export type { OutputUnit, SchemaDraft, ValidationResult };
+/**
+ * Options for `createFormSpecValidator`.
+ *
+ * @public
+ */
+export interface CreateValidatorOptions {
+    /**
+     * The JSON Schema draft version to validate against.
+     *
+     * FormSpec generates schemas targeting JSON Schema 2020-12.
+     *
+     * @defaultValue `"2020-12"`
+     */
+    draft?: SchemaDraft;
+    /**
+     * When `true`, validation stops after the first error.
+     * When `false`, all errors are collected.
+     *
+     * @defaultValue `true`
+     */
+    shortCircuit?: boolean;
+}
+/**
+ * Creates a `Validator` configured for FormSpec-generated JSON Schemas.
+ *
+ * The returned `Validator` uses JSON Schema draft 2020-12 by default and
+ * silently ignores `x-formspec-*` extension keywords — no vocabulary
+ * registration is needed.
+ *
+ * @param schema - A JSON Schema object (typically generated by `@formspec/build`).
+ * @param options - Optional configuration for draft version and error collection behavior.
+ * @returns A `Validator` instance whose `validate()` method returns a `ValidationResult`.
+ *
+ * @public
+ */
+export declare function createFormSpecValidator(schema: Record<string, unknown>, options?: CreateValidatorOptions): Validator;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAU,WAAW,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE/F,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,SAAS,CAOX"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// src/index.ts
+import { Validator } from "@cfworker/json-schema";
+function createFormSpecValidator(schema, options) {
+  const draft = options?.draft ?? "2020-12";
+  const shortCircuit = options?.shortCircuit ?? true;
+  return new Validator(schema, draft, shortCircuit);
+}
+export {
+  Validator,
+  createFormSpecValidator
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@formspec/validator` — JSON Schema validator for FormSpec\n *\n * Backed by {@link https://github.com/cfworker/cfworker/tree/main/packages/json-schema | @cfworker/json-schema},\n * this package validates data against FormSpec-generated JSON Schemas in any\n * JavaScript runtime — including secure environments that disallow `new Function()`\n * (e.g., Cloudflare Workers).\n *\n * Unlike Ajv, `@cfworker/json-schema` silently ignores unknown keywords, so\n * FormSpec's `x-formspec-*` extension keywords require no vocabulary registration.\n *\n * @example\n * ```typescript\n * import { createFormSpecValidator } from \"@formspec/validator\";\n *\n * const validator = createFormSpecValidator({\n *   type: \"object\",\n *   required: [\"name\"],\n *   properties: {\n *     name: { type: \"string\" },\n *     country: { type: \"string\", \"x-formspec-source\": \"countries\" },\n *   },\n * });\n *\n * const result = validator.validate({ name: \"Alice\", country: \"US\" });\n * // result.valid === true\n * ```\n *\n * @packageDocumentation\n */\n\nimport { Validator } from \"@cfworker/json-schema\";\nimport type { OutputUnit, Schema, SchemaDraft, ValidationResult } from \"@cfworker/json-schema\";\n\nexport { Validator };\nexport type { OutputUnit, SchemaDraft, ValidationResult };\n\n/**\n * Options for `createFormSpecValidator`.\n *\n * @public\n */\nexport interface CreateValidatorOptions {\n  /**\n   * The JSON Schema draft version to validate against.\n   *\n   * FormSpec generates schemas targeting JSON Schema 2020-12.\n   *\n   * @defaultValue `\"2020-12\"`\n   */\n  draft?: SchemaDraft;\n\n  /**\n   * When `true`, validation stops after the first error.\n   * When `false`, all errors are collected.\n   *\n   * @defaultValue `true`\n   */\n  shortCircuit?: boolean;\n}\n\n/**\n * Creates a `Validator` configured for FormSpec-generated JSON Schemas.\n *\n * The returned `Validator` uses JSON Schema draft 2020-12 by default and\n * silently ignores `x-formspec-*` extension keywords — no vocabulary\n * registration is needed.\n *\n * @param schema - A JSON Schema object (typically generated by `@formspec/build`).\n * @param options - Optional configuration for draft version and error collection behavior.\n * @returns A `Validator` instance whose `validate()` method returns a `ValidationResult`.\n *\n * @public\n */\nexport function createFormSpecValidator(\n  schema: Record<string, unknown>,\n  options?: CreateValidatorOptions,\n): Validator {\n  const draft = options?.draft ?? \"2020-12\";\n  const shortCircuit = options?.shortCircuit ?? true;\n  // Safe cast: Schema has `[key: string]: any`, so every Record<string, unknown>\n  // structurally satisfies it. We keep the public parameter as Record<string, unknown>\n  // to avoid coupling consumers to @cfworker/json-schema's Schema type.\n  return new Validator(schema as Schema, draft, shortCircuit);\n}\n"],"mappings":";AA+BA,SAAS,iBAAiB;AA2CnB,SAAS,wBACd,QACA,SACW;AACX,QAAM,QAAQ,SAAS,SAAS;AAChC,QAAM,eAAe,SAAS,gBAAgB;AAI9C,SAAO,IAAI,UAAU,QAAkB,OAAO,YAAY;AAC5D;","names":[]}

package/dist/validator.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `@formspec/validator` — JSON Schema validator for FormSpec
+ *
+ * Backed by {@link https://github.com/cfworker/cfworker/tree/main/packages/json-schema | @cfworker/json-schema},
+ * this package validates data against FormSpec-generated JSON Schemas in any
+ * JavaScript runtime — including secure environments that disallow `new Function()`
+ * (e.g., Cloudflare Workers).
+ *
+ * Unlike Ajv, `@cfworker/json-schema` silently ignores unknown keywords, so
+ * FormSpec's `x-formspec-*` extension keywords require no vocabulary registration.
+ *
+ * @example
+ * ```typescript
+ * import { createFormSpecValidator } from "@formspec/validator";
+ *
+ * const validator = createFormSpecValidator({
+ *   type: "object",
+ *   required: ["name"],
+ *   properties: {
+ *     name: { type: "string" },
+ *     country: { type: "string", "x-formspec-source": "countries" },
+ *   },
+ * });
+ *
+ * const result = validator.validate({ name: "Alice", country: "US" });
+ * // result.valid === true
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { OutputUnit } from '@cfworker/json-schema';
+import type { SchemaDraft } from '@cfworker/json-schema';
+import type { ValidationResult } from '@cfworker/json-schema';
+import { Validator } from '@cfworker/json-schema';
+
+/**
+ * Creates a `Validator` configured for FormSpec-generated JSON Schemas.
+ *
+ * The returned `Validator` uses JSON Schema draft 2020-12 by default and
+ * silently ignores `x-formspec-*` extension keywords — no vocabulary
+ * registration is needed.
+ *
+ * @param schema - A JSON Schema object (typically generated by `@formspec/build`).
+ * @param options - Optional configuration for draft version and error collection behavior.
+ * @returns A `Validator` instance whose `validate()` method returns a `ValidationResult`.
+ *
+ * @public
+ */
+export declare function createFormSpecValidator(schema: Record<string, unknown>, options?: CreateValidatorOptions): Validator;
+
+/**
+ * Options for `createFormSpecValidator`.
+ *
+ * @public
+ */
+export declare interface CreateValidatorOptions {
+    /**
+     * The JSON Schema draft version to validate against.
+     *
+     * FormSpec generates schemas targeting JSON Schema 2020-12.
+     *
+     * @defaultValue `"2020-12"`
+     */
+    draft?: SchemaDraft;
+    /**
+     * When `true`, validation stops after the first error.
+     * When `false`, all errors are collected.
+     *
+     * @defaultValue `true`
+     */
+    shortCircuit?: boolean;
+}
+
+export { OutputUnit }
+
+export { SchemaDraft }
+
+export { ValidationResult }
+
+export { Validator }
+
+export { }

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@formspec/validator",
+  "version": "0.1.0-alpha.12",
+  "description": "JSON Schema validator for FormSpec — backed by @cfworker/json-schema, safe for secure runtimes",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/validator.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/validator.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "formspec",
+    "validator",
+    "jsonschema",
+    "cloudflare-workers"
+  ],
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly && api-extractor run --local",
+    "clean": "rm -rf dist temp",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "api-extractor": "api-extractor run",
+    "api-extractor:local": "api-extractor run --local",
+    "api-documenter": "api-documenter markdown -i temp -o docs"
+  }
+}