@queryweave/standard-schema 0.1.0-alpha.1 → 0.1.0-beta.1

package/README.md

@@ -2,15 +2,26 @@
 
 Standard Schema interoperability for QueryWeave parameters and models.
 
+```sh
+pnpm add @queryweave/standard-schema
+```
+
 ```ts
 import { fromStandardSchema } from "@queryweave/standard-schema";
 
 param.text().refine(fromStandardSchema(schema)).optional();
+param.text().refine(fromStandardSchema(digitsToNumber, { encode: (value) => String(value) }));
+param.text().refine(fromStandardSchema(slugIsFree, { async: true }));
 defineQueryModel(definitions, { refine: [fromStandardSchema(crossFieldSchema)] });
 ```
 
 The package depends on `@standard-schema/spec` and nothing else. Zod, Valibot, and ArkType are
 development-only dependencies of the test suite, and one shared compatibility contract runs against
-all three. Vendor errors are normalized into QueryWeave `validation_failed` issues.
+all three. Vendor errors — and vendor exceptions — are normalized into QueryWeave
+`validation_failed` issues.
+
+A schema that changes the value's type must be given `encode`, the inverse used to write the value
+back to a URL. Asynchronous schemas resolve through `model.decodeAsync` and the runtime's pending
+state; declare them with `async: true` so the synchronous decode does not start them.
 
-Asynchronous schemas resolve through `model.decodeAsync`.
+Documentation: https://queryweave-docs.vercel.app/validation/

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { QueryRefinement } from "@queryweave/core";
+import { QueryRefinement, QueryTransform } from "@queryweave/core";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/index.d.ts
 /**
@@ -12,16 +12,32 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
 interface StandardSchemaRefinementOptions {
   /** Label used for diagnostics. Defaults to the schema's own vendor name. */
   readonly name?: string | undefined;
+  /**
+   * Declare that the schema validates asynchronously. The synchronous decode then reports
+   * `async_required` without starting the validation.
+   */
+  readonly async?: boolean | undefined;
 }
-/** The refinement produced from a Standard Schema. */
+/** Options for a schema whose output type differs from its input. */
+interface StandardSchemaTransformOptions<TSchema extends StandardSchemaV1> extends StandardSchemaRefinementOptions {
+  /** Map a validated output back to the input the schema accepts, for writing to a URL. */
+  encode(value: StandardSchemaV1.InferOutput<TSchema>): StandardSchemaV1.InferInput<TSchema>;
+}
+/** The refinement produced from a validating or narrowing Standard Schema. */
 type StandardSchemaRefinement<TSchema extends StandardSchemaV1> = QueryRefinement<StandardSchemaV1.InferInput<TSchema>, StandardSchemaV1.InferOutput<TSchema>>;
+/** The refinement produced from a transforming Standard Schema together with its inverse. */
+type StandardSchemaTransform<TSchema extends StandardSchemaV1> = QueryTransform<StandardSchemaV1.InferInput<TSchema>, StandardSchemaV1.InferOutput<TSchema>>;
 /**
  * Adapt any Standard Schema into a QueryWeave refinement.
  *
- * Synchronous schemas keep synchronous decoding available. Asynchronous schemas resolve through
- * `model.decodeAsync`, and transformed outputs flow through to the parameter's value type.
+ * A schema that only validates, or narrows its type, needs no options. A schema that transforms
+ * its input into another type must be given `encode`, so the transformed value can be written
+ * back to a URL; the returned transform is what `refine()` accepts for such a schema.
+ * Synchronous schemas keep synchronous decoding available; asynchronous schemas resolve through
+ * the asynchronous decode path.
  */
+declare function fromStandardSchema<TSchema extends StandardSchemaV1>(schema: TSchema, options: StandardSchemaTransformOptions<TSchema>): StandardSchemaTransform<TSchema>;
 declare function fromStandardSchema<TSchema extends StandardSchemaV1>(schema: TSchema, options?: StandardSchemaRefinementOptions): StandardSchemaRefinement<TSchema>;
 //#endregion
-export { StandardSchemaRefinement, StandardSchemaRefinementOptions, fromStandardSchema };
+export { StandardSchemaRefinement, StandardSchemaRefinementOptions, StandardSchemaTransform, StandardSchemaTransformOptions, fromStandardSchema };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;UAgBiB;;WAEN;;;KAIC,yBAAyB,gBAAgB,oBAAoB,gBACvE,iBAAiB,WAAW,UAC5B,iBAAiB,YAAY;;;;;;;iBAqCf,mBAAmB,gBAAgB,kBACjD,QAAQ,SACR,UAAS,kCACR,yBAAyB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;UAiBiB;;WAEN;;;;;WAKA;;;UAIM,+BACf,gBAAgB,0BACR;;EAER,OAAO,OAAO,iBAAiB,YAAY,WAAW,iBAAiB,WAAW;;;KAIxE,yBAAyB,gBAAgB,oBAAoB,gBACvE,iBAAiB,WAAW,UAC5B,iBAAiB,YAAY;;KAInB,wBAAwB,gBAAgB,oBAAoB,eACtE,iBAAiB,WAAW,UAC5B,iBAAiB,YAAY;;;;;;;;;;iBAgDf,mBAAmB,gBAAgB,kBACjD,QAAQ,SACR,SAAS,+BAA+B,WACvC,wBAAwB;iBACX,mBAAmB,gBAAgB,kBACjD,QAAQ,SACR,UAAU,kCACT,yBAAyB"}

package/dist/index.js

@@ -19,22 +19,25 @@ function toRefinementResult(result) {
 		}))
 	};
 }
-/**
-* Adapt any Standard Schema into a QueryWeave refinement.
-*
-* Synchronous schemas keep synchronous decoding available. Asynchronous schemas resolve through
-* `model.decodeAsync`, and transformed outputs flow through to the parameter's value type.
-*/
+function isThenable(value) {
+	return typeof value === "object" && value !== null && typeof value.then === "function";
+}
 function fromStandardSchema(schema, options = {}) {
 	const standard = schema["~standard"];
-	return {
+	const settle = (result) => toRefinementResult(result);
+	const refinement = {
 		name: options.name ?? standard.vendor,
+		async: options.async,
 		refine: (value) => {
 			const outcome = standard.validate(value);
-			if (outcome instanceof Promise) return outcome.then((resolved) => toRefinementResult(resolved));
-			return toRefinementResult(outcome);
+			return isThenable(outcome) ? outcome.then(settle) : settle(outcome);
 		}
 	};
+	if ("encode" in options) return {
+		...refinement,
+		encode: (value) => options.encode(value)
+	};
+	return refinement;
 }
 
 //#endregion

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type {\n  QueryRefinement,\n  QueryRefinementIssue,\n  QueryRefinementResult,\n} from \"@queryweave/core\";\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * Standard Schema interoperability.\n *\n * The validator stays a development-time choice: this package depends on the specification alone,\n * never on Zod, Valibot, ArkType, or any other runtime. Vendor errors are normalized so consumers\n * only ever see QueryWeave issues.\n */\n\n/** Options accepted by {@link fromStandardSchema}. */\nexport interface StandardSchemaRefinementOptions {\n  /** Label used for diagnostics. Defaults to the schema's own vendor name. */\n  readonly name?: string | undefined;\n}\n\n/** The refinement produced from a Standard Schema. */\nexport type StandardSchemaRefinement<TSchema extends StandardSchemaV1> = QueryRefinement<\n  StandardSchemaV1.InferInput<TSchema>,\n  StandardSchemaV1.InferOutput<TSchema>\n>;\n\nfunction toPath(segments: StandardSchemaV1.Issue[\"path\"]): readonly PropertyKey[] | undefined {\n  if (segments === undefined) {\n    return undefined;\n  }\n  const path: PropertyKey[] = [];\n  for (const segment of segments) {\n    if (typeof segment === \"object\") {\n      path.push(segment.key);\n    } else {\n      path.push(segment);\n    }\n  }\n  return path;\n}\n\nfunction toRefinementResult<TOutput>(\n  result: StandardSchemaV1.Result<TOutput>,\n): QueryRefinementResult<TOutput> {\n  if (result.issues === undefined) {\n    return { ok: true, value: result.value };\n  }\n  const issues: QueryRefinementIssue[] = result.issues.map((issue) => ({\n    message: issue.message,\n    path: toPath(issue.path),\n  }));\n  return { ok: false, issues };\n}\n\n/**\n * Adapt any Standard Schema into a QueryWeave refinement.\n *\n * Synchronous schemas keep synchronous decoding available. Asynchronous schemas resolve through\n * `model.decodeAsync`, and transformed outputs flow through to the parameter's value type.\n */\nexport function fromStandardSchema<TSchema extends StandardSchemaV1>(\n  schema: TSchema,\n  options: StandardSchemaRefinementOptions = {},\n): StandardSchemaRefinement<TSchema> {\n  const standard = schema[\"~standard\"];\n\n  return {\n    name: options.name ?? standard.vendor,\n    refine: (value) => {\n      const outcome = standard.validate(value);\n      if (outcome instanceof Promise) {\n        return outcome.then((resolved) =>\n          toRefinementResult(\n            resolved as StandardSchemaV1.Result<StandardSchemaV1.InferOutput<TSchema>>,\n          ),\n        );\n      }\n      return toRefinementResult(\n        outcome as StandardSchemaV1.Result<StandardSchemaV1.InferOutput<TSchema>>,\n      );\n    },\n  };\n}\n"],"mappings":";AA2BA,SAAS,OAAO,UAA8E;CAC5F,IAAI,aAAa,QACf;CAEF,MAAM,OAAsB,CAAC;CAC7B,KAAK,MAAM,WAAW,UACpB,IAAI,OAAO,YAAY,UACrB,KAAK,KAAK,QAAQ,GAAG;MAErB,KAAK,KAAK,OAAO;CAGrB,OAAO;AACT;AAEA,SAAS,mBACP,QACgC;CAChC,IAAI,OAAO,WAAW,QACpB,OAAO;EAAE,IAAI;EAAM,OAAO,OAAO;CAAM;CAMzC,OAAO;EAAE,IAAI;EAAO,QAJmB,OAAO,OAAO,KAAK,WAAW;GACnE,SAAS,MAAM;GACf,MAAM,OAAO,MAAM,IAAI;EACzB,EACyB;CAAE;AAC7B;;;;;;;AAQA,SAAgB,mBACd,QACA,UAA2C,CAAC,GACT;CACnC,MAAM,WAAW,OAAO;CAExB,OAAO;EACL,MAAM,QAAQ,QAAQ,SAAS;EAC/B,SAAS,UAAU;GACjB,MAAM,UAAU,SAAS,SAAS,KAAK;GACvC,IAAI,mBAAmB,SACrB,OAAO,QAAQ,MAAM,aACnB,mBACE,QACF,CACF;GAEF,OAAO,mBACL,OACF;EACF;CACF;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type {\n  QueryRefinement,\n  QueryRefinementIssue,\n  QueryRefinementResult,\n  QueryTransform,\n} from \"@queryweave/core\";\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * Standard Schema interoperability.\n *\n * The validator stays a development-time choice: this package depends on the specification alone,\n * never on Zod, Valibot, ArkType, or any other runtime. Vendor errors are normalized so consumers\n * only ever see QueryWeave issues.\n */\n\n/** Options accepted by {@link fromStandardSchema}. */\nexport interface StandardSchemaRefinementOptions {\n  /** Label used for diagnostics. Defaults to the schema's own vendor name. */\n  readonly name?: string | undefined;\n  /**\n   * Declare that the schema validates asynchronously. The synchronous decode then reports\n   * `async_required` without starting the validation.\n   */\n  readonly async?: boolean | undefined;\n}\n\n/** Options for a schema whose output type differs from its input. */\nexport interface StandardSchemaTransformOptions<\n  TSchema extends StandardSchemaV1,\n> extends StandardSchemaRefinementOptions {\n  /** Map a validated output back to the input the schema accepts, for writing to a URL. */\n  encode(value: StandardSchemaV1.InferOutput<TSchema>): StandardSchemaV1.InferInput<TSchema>;\n}\n\n/** The refinement produced from a validating or narrowing Standard Schema. */\nexport type StandardSchemaRefinement<TSchema extends StandardSchemaV1> = QueryRefinement<\n  StandardSchemaV1.InferInput<TSchema>,\n  StandardSchemaV1.InferOutput<TSchema>\n>;\n\n/** The refinement produced from a transforming Standard Schema together with its inverse. */\nexport type StandardSchemaTransform<TSchema extends StandardSchemaV1> = QueryTransform<\n  StandardSchemaV1.InferInput<TSchema>,\n  StandardSchemaV1.InferOutput<TSchema>\n>;\n\nfunction toPath(segments: StandardSchemaV1.Issue[\"path\"]): readonly PropertyKey[] | undefined {\n  if (segments === undefined) {\n    return undefined;\n  }\n  const path: PropertyKey[] = [];\n  for (const segment of segments) {\n    if (typeof segment === \"object\") {\n      path.push(segment.key);\n    } else {\n      path.push(segment);\n    }\n  }\n  return path;\n}\n\nfunction toRefinementResult<TOutput>(\n  result: StandardSchemaV1.Result<TOutput>,\n): QueryRefinementResult<TOutput> {\n  if (result.issues === undefined) {\n    return { ok: true, value: result.value };\n  }\n  const issues: QueryRefinementIssue[] = result.issues.map((issue) => ({\n    message: issue.message,\n    path: toPath(issue.path),\n  }));\n  return { ok: false, issues };\n}\n\nfunction isThenable(value: unknown): value is PromiseLike<unknown> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { then?: unknown }).then === \"function\"\n  );\n}\n\n/**\n * Adapt any Standard Schema into a QueryWeave refinement.\n *\n * A schema that only validates, or narrows its type, needs no options. A schema that transforms\n * its input into another type must be given `encode`, so the transformed value can be written\n * back to a URL; the returned transform is what `refine()` accepts for such a schema.\n * Synchronous schemas keep synchronous decoding available; asynchronous schemas resolve through\n * the asynchronous decode path.\n */\nexport function fromStandardSchema<TSchema extends StandardSchemaV1>(\n  schema: TSchema,\n  options: StandardSchemaTransformOptions<TSchema>,\n): StandardSchemaTransform<TSchema>;\nexport function fromStandardSchema<TSchema extends StandardSchemaV1>(\n  schema: TSchema,\n  options?: StandardSchemaRefinementOptions,\n): StandardSchemaRefinement<TSchema>;\nexport function fromStandardSchema<TSchema extends StandardSchemaV1>(\n  schema: TSchema,\n  options: StandardSchemaRefinementOptions | StandardSchemaTransformOptions<TSchema> = {},\n): StandardSchemaRefinement<TSchema> {\n  type Output = StandardSchemaV1.InferOutput<TSchema>;\n  const standard = schema[\"~standard\"];\n  const settle = (result: unknown): QueryRefinementResult<Output> =>\n    toRefinementResult(result as StandardSchemaV1.Result<Output>);\n\n  const refinement: StandardSchemaRefinement<TSchema> = {\n    name: options.name ?? standard.vendor,\n    async: options.async,\n    refine: (value) => {\n      const outcome = standard.validate(value);\n      return isThenable(outcome) ? outcome.then(settle) : settle(outcome);\n    },\n  };\n  if (\"encode\" in options) {\n    return { ...refinement, encode: (value) => options.encode(value) };\n  }\n  return refinement;\n}\n"],"mappings":";AA+CA,SAAS,OAAO,UAA8E;CAC5F,IAAI,aAAa,QACf;CAEF,MAAM,OAAsB,CAAC;CAC7B,KAAK,MAAM,WAAW,UACpB,IAAI,OAAO,YAAY,UACrB,KAAK,KAAK,QAAQ,GAAG;MAErB,KAAK,KAAK,OAAO;CAGrB,OAAO;AACT;AAEA,SAAS,mBACP,QACgC;CAChC,IAAI,OAAO,WAAW,QACpB,OAAO;EAAE,IAAI;EAAM,OAAO,OAAO;CAAM;CAMzC,OAAO;EAAE,IAAI;EAAO,QAJmB,OAAO,OAAO,KAAK,WAAW;GACnE,SAAS,MAAM;GACf,MAAM,OAAO,MAAM,IAAI;EACzB,EACyB;CAAE;AAC7B;AAEA,SAAS,WAAW,OAA+C;CACjE,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA6B,SAAS;AAElD;AAmBA,SAAgB,mBACd,QACA,UAAqF,CAAC,GACnD;CAEnC,MAAM,WAAW,OAAO;CACxB,MAAM,UAAU,WACd,mBAAmB,MAAyC;CAE9D,MAAM,aAAgD;EACpD,MAAM,QAAQ,QAAQ,SAAS;EAC/B,OAAO,QAAQ;EACf,SAAS,UAAU;GACjB,MAAM,UAAU,SAAS,SAAS,KAAK;GACvC,OAAO,WAAW,OAAO,IAAI,QAAQ,KAAK,MAAM,IAAI,OAAO,OAAO;EACpE;CACF;CACA,IAAI,YAAY,SACd,OAAO;EAAE,GAAG;EAAY,SAAS,UAAU,QAAQ,OAAO,KAAK;CAAE;CAEnE,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@queryweave/standard-schema",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-beta.1",
   "description": "Standard Schema interoperability contracts for QueryWeave.",
   "keywords": [
     "query",
@@ -39,13 +39,13 @@
   },
   "dependencies": {
     "@standard-schema/spec": "1.1.0",
-    "@queryweave/core": "0.1.0-alpha.1"
+    "@queryweave/core": "0.1.0-beta.1"
   },
   "devDependencies": {
     "@queryweave/typescript-config": "0.0.0"
   },
   "engines": {
-    "node": ">=24.18.0"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "build": "tsdown",