@mpen/valibot-extras 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# @mpen/valibot-extras
+
+Extras and extensions for [Valibot](https://valibot.dev/).
+
+## Motivation
+
+Valibot's built-in string validators have some surprising behaviors:
+
+### `v.string()` accepts ill-formed strings
+
+`v.string()` happily accepts strings containing lone/unpaired UTF-16 surrogates:
+
+```ts
+v.safeParse(v.string(), '\ud800').success // ✅ true — but this is not valid Unicode!
+```
+
+These ill-formed strings can cause issues downstream (e.g. when serializing to JSON, sending over the network, or storing in a database).
+
+### `v.minLength` / `v.maxLength` count code units, not characters
+
+Valibot's length validators use JavaScript's `.length` property, which counts UTF-16 code units — not visible characters. Characters outside the Basic Multilingual Plane (emoji, CJK ideographs, etc.) are represented as surrogate pairs and count as **2**:
+
+```ts
+// '𠮷' is a single character, but 2 UTF-16 code units
+v.safeParse(v.pipe(v.string(), v.minLength(2)), '𠮷').success // ✅ true — '𠮷'.length === 2
+
+// '𠮷𠮷' is 2 characters, but 4 code units
+v.safeParse(v.pipe(v.string(), v.maxLength(3)), '𠮷𠮷').success // ❌ false — despite being only 2 chars
+```
+
+This is particularly problematic when enforcing limits that should match database column widths (e.g. MySQL's `VARCHAR(n)`, which counts characters, not bytes or code units).
+
+## Installation
+
+```bash
+bun add @mpen/valibot-extras
+```
+
+## API
+
+### `wellFormed(message?)`
+
+A Valibot action that rejects strings containing lone/unpaired UTF-16 surrogates (uses [`String.prototype.isWellFormed()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/isWellFormed)):
+
+```ts
+import * as v from 'valibot'
+import * as vx from '@mpen/valibot-extras'
+
+const schema = v.pipe(v.string(), vx.wellFormed())
+
+v.safeParse(schema, 'hello 𠮷').success  // ✅ true
+v.safeParse(schema, '\ud800').success    // ❌ false
+```
+
+### `unicodeString(message?)`
+
+Shorthand for `v.pipe(v.string(), wellFormed())` — a string schema that only accepts well-formed Unicode:
+
+```ts
+import * as vx from '@mpen/valibot-extras'
+
+const schema = vx.unicodeString()
+
+v.safeParse(schema, 'abc').success     // ✅ true
+v.safeParse(schema, '\ud800').success  // ❌ false
+```
+
+### `minCharLength(requirement, message?)`
+
+Like `v.minLength`, but counts Unicode code points (characters) instead of UTF-16 code units:
+
+```ts
+import * as v from 'valibot'
+import * as vx from '@mpen/valibot-extras'
+
+const schema = v.pipe(v.string(), vx.minCharLength(3))
+
+v.safeParse(schema, '𠮷𠮷𠮷').success  // ✅ true — 3 characters
+v.safeParse(schema, '𠮷𠮷').success    // ❌ false — only 2 characters
+```
+
+### `maxCharLength(requirement, message?)`
+
+Like `v.maxLength`, but counts Unicode code points instead of UTF-16 code units:
+
+```ts
+import * as v from 'valibot'
+import * as vx from '@mpen/valibot-extras'
+
+const schema = v.pipe(v.string(), vx.maxCharLength(3))
+
+v.safeParse(schema, '𠮷𠮷𠮷').success   // ✅ true — 3 characters
+v.safeParse(schema, '𠮷𠮷𠮷𠮷').success  // ❌ false — 4 characters
+```
+
+### `charLength(requirement, message?)`
+
+Like `v.length`, but counts Unicode code points instead of UTF-16 code units:
+
+```ts
+import * as v from 'valibot'
+import * as vx from '@mpen/valibot-extras'
+
+const schema = v.pipe(v.string(), vx.charLength(3))
+
+v.safeParse(schema, '𠮷𠮷𠮷').success   // ✅ true — exactly 3 characters
+v.safeParse(schema, '𠮷𠮷').success     // ❌ false — only 2
+v.safeParse(schema, '𠮷𠮷𠮷𠮷').success  // ❌ false — 4
+```
+
+### `toJsonSchema(schema, config?)`
+
+Converts a Valibot schema to JSON Schema, with support for custom JSON Schema annotations attached via [`attachJsonSchema`](#attachjsonschematarget-jsonschema).
+
+This wraps `@valibot/to-json-schema` and adds `overrideSchema`/`overrideAction` hooks that look for schemas attached via the `jsonSchemaSymbol`. Attached schemas are merged into the converted output, preserving properties from the base conversion.
+
+```ts
+import * as v from 'valibot'
+import * as vx from '@mpen/valibot-extras'
+
+const schema = v.pipe(v.string(), vx.minCharLength(5), vx.maxCharLength(10))
+const jsonSchema = vx.toJsonSchema(schema)
+// { type: 'string', minLength: 5, maxLength: 10, $schema: '...' }
+```
+
+### `attachJsonSchema(target, jsonSchema)`
+
+Attaches a custom JSON Schema fragment to any Valibot schema or action via a non-enumerable Symbol property. This is used internally by `wellFormed`, `minCharLength`, etc. to make them compatible with `toJsonSchema`, but you can use it to annotate your own custom actions:
+
+```ts
+import * as v from 'valibot'
+import * as vx from '@mpen/valibot-extras'
+
+const myAction = v.check((input: string) => input.startsWith('https://'), 'Must be HTTPS')
+const annotated = vx.attachJsonSchema(myAction, { format: 'uri' })
+
+const schema = v.pipe(v.string(), annotated)
+const jsonSchema = vx.toJsonSchema(schema)
+// { type: 'string', format: 'uri', $schema: '...' }
+```
+
+### `jsonSchemaSymbol`
+
+The Symbol used by [`attachJsonSchema`](#attachjsonschematarget-jsonschema) to store the JSON Schema on a Valibot schema or action. Exposed for advanced use cases (e.g. reading back attached schemas).
+
+### JSON Schema Compatibility
+
+All string validators in this package are compatible with `@valibot/to-json-schema` (and the included `toJsonSchema` wrapper). The `minCharLength` / `maxCharLength` / `charLength` actions produce the standard `minLength` / `maxLength` JSON Schema keywords.

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+import * as v from "valibot";
+import { ConversionConfig, JsonSchema } from "@valibot/to-json-schema";
+
+//#region src/strings.d.ts
+/**
+ * Creates a Valibot action to validate that a string is well-formed Unicode.
+ *
+ * This checks that the string contains no lone/unpaired UTF-16 surrogate characters.
+ *
+ * @example
+ * ```ts
+ * import * as v from 'valibot';
+ * import { wellFormed } from '@mpen/valibot-extras';
+ *
+ * const schema = v.pipe(v.string(), wellFormed());
+ * ```
+ *
+ * @param message - The error message.
+ * @returns The Valibot action.
+ */
+declare function wellFormed(message?: string): v.CheckAction<string, string>;
+/**
+ * Creates a Valibot schema to validate a well-formed Unicode string.
+ *
+ * This combines `v.string()` with the [`wellFormed`]{@link wellFormed} validation action.
+ *
+ * @example
+ * ```ts
+ * import { unicodeString } from '@mpen/valibot-extras';
+ *
+ * const schema = unicodeString('Invalid string');
+ * ```
+ *
+ * @param message - The error message.
+ * @returns The Valibot schema.
+ */
+declare function unicodeString(message?: string): v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, string>]>;
+/**
+ * Creates a Valibot action to validate the minimum character length of a string (counting Unicode code points).
+ *
+ * This validator counts UTF-16 surrogate pairs as a single character (matching MySQL's `VARCHAR` length behavior).
+ * See also [`maxCharLength`]{@link maxCharLength} and [`charLength`]{@link charLength}.
+ *
+ * @example
+ * ```ts
+ * import * as v from 'valibot';
+ * import { minCharLength } from '@mpen/valibot-extras';
+ *
+ * const schema = v.pipe(v.string(), minCharLength(5));
+ * ```
+ *
+ * @param requirement - The minimum character length requirement.
+ * @param message - The error message.
+ * @returns The Valibot action.
+ */
+declare function minCharLength<const TRequirement extends number>(requirement: TRequirement, message?: string): never;
+/**
+ * Creates a Valibot action to validate the maximum character length of a string (counting Unicode code points).
+ *
+ * This validator counts UTF-16 surrogate pairs as a single character (matching MySQL's `VARCHAR` length behavior).
+ * See also [`minCharLength`]{@link minCharLength} and [`charLength`]{@link charLength}.
+ *
+ * @example
+ * ```ts
+ * import * as v from 'valibot';
+ * import { maxCharLength } from '@mpen/valibot-extras';
+ *
+ * const schema = v.pipe(v.string(), maxCharLength(10));
+ * ```
+ *
+ * @param requirement - The maximum character length requirement.
+ * @param message - The error message.
+ * @returns The Valibot action.
+ */
+declare function maxCharLength<const TRequirement extends number>(requirement: TRequirement, message?: string): never;
+/**
+ * Creates a Valibot action to validate the exact character length of a string (counting Unicode code points).
+ *
+ * This validator counts UTF-16 surrogate pairs as a single character.
+ * See also [`minCharLength`]{@link minCharLength} and [`maxCharLength`]{@link maxCharLength}.
+ *
+ * @example
+ * ```ts
+ * import * as v from 'valibot';
+ * import { charLength } from '@mpen/valibot-extras';
+ *
+ * const schema = v.pipe(v.string(), charLength(5));
+ * ```
+ *
+ * @param requirement - The exact character length requirement.
+ * @param message - The error message.
+ * @returns The Valibot action.
+ */
+declare function charLength<const TRequirement extends number>(requirement: TRequirement, message?: string): never;
+//#endregion
+//#region src/json-schema.d.ts
+/**
+ * The symbol used to attach a custom JSON Schema to a Valibot schema or action.
+ */
+declare const jsonSchemaSymbol: unique symbol;
+/**
+ * Attaches a custom JSON Schema to a Valibot schema or action using a Symbol.
+ *
+ * @param target - The target Valibot schema or action.
+ * @param jsonSchema - The JSON Schema to attach.
+ * @returns The target object with the attached JSON Schema.
+ */
+declare function attachJsonSchema<T extends object>(target: T, jsonSchema: JsonSchema): T;
+/**
+ * Converts a Valibot schema to JSON Schema, with support for custom attached JSON Schemas.
+ *
+ * This wraps `@valibot/to-json-schema`'s `toJsonSchema` and implements `overrideSchema`
+ * and `overrideAction` to look for schemas attached via [`attachJsonSchema`]{@link attachJsonSchema}.
+ * Attached schemas are merged into the converted JSON Schema, preserving properties from
+ * the base conversion.
+ *
+ * @example
+ * ```ts
+ * import * as v from 'valibot';
+ * import { toJsonSchema, unicodeString } from '@mpen/valibot-extras';
+ *
+ * const schema = unicodeString();
+ * const jsonSchema = toJsonSchema(schema);
+ * ```
+ *
+ * @param schema - The Valibot schema to convert.
+ * @param config - Optional conversion configuration.
+ * @returns The generated JSON Schema.
+ */
+declare function toJsonSchema(schema: v.GenericSchema, config?: ConversionConfig): JsonSchema;
+//#endregion
+export { attachJsonSchema, charLength, jsonSchemaSymbol, maxCharLength, minCharLength, toJsonSchema, unicodeString, wellFormed };

package/dist/index.js

@@ -0,0 +1,211 @@
+import * as v from "valibot";
+import { toJsonSchema as toJsonSchema$1 } from "@valibot/to-json-schema";
+//#region src/json-schema.ts
+/**
+* The symbol used to attach a custom JSON Schema to a Valibot schema or action.
+*/
+const jsonSchemaSymbol = Symbol("jsonSchema");
+/**
+* Attaches a custom JSON Schema to a Valibot schema or action using a Symbol.
+*
+* @param target - The target Valibot schema or action.
+* @param jsonSchema - The JSON Schema to attach.
+* @returns The target object with the attached JSON Schema.
+*/
+function attachJsonSchema(target, jsonSchema) {
+	Object.defineProperty(target, jsonSchemaSymbol, {
+		value: jsonSchema,
+		configurable: true,
+		enumerable: false,
+		writable: true
+	});
+	return target;
+}
+/**
+* Converts a Valibot schema to JSON Schema, with support for custom attached JSON Schemas.
+*
+* This wraps `@valibot/to-json-schema`'s `toJsonSchema` and implements `overrideSchema`
+* and `overrideAction` to look for schemas attached via [`attachJsonSchema`]{@link attachJsonSchema}.
+* Attached schemas are merged into the converted JSON Schema, preserving properties from
+* the base conversion.
+*
+* @example
+* ```ts
+* import * as v from 'valibot';
+* import { toJsonSchema, unicodeString } from '@mpen/valibot-extras';
+*
+* const schema = unicodeString();
+* const jsonSchema = toJsonSchema(schema);
+* ```
+*
+* @param schema - The Valibot schema to convert.
+* @param config - Optional conversion configuration.
+* @returns The generated JSON Schema.
+*/
+function toJsonSchema(schema, config) {
+	return toJsonSchema$1(schema, {
+		...config,
+		overrideSchema(context) {
+			const schemaOverride = context.valibotSchema[jsonSchemaSymbol];
+			if (schemaOverride !== void 0) return {
+				...context.jsonSchema,
+				...schemaOverride
+			};
+			return config?.overrideSchema?.(context);
+		},
+		overrideAction(context) {
+			const actionOverride = context.valibotAction[jsonSchemaSymbol];
+			if (actionOverride !== void 0) return {
+				...context.jsonSchema,
+				...actionOverride
+			};
+			return config?.overrideAction?.(context);
+		}
+	});
+}
+//#endregion
+//#region src/strings.ts
+/**
+* Creates a Valibot action to validate that a string is well-formed Unicode.
+*
+* This checks that the string contains no lone/unpaired UTF-16 surrogate characters.
+*
+* @example
+* ```ts
+* import * as v from 'valibot';
+* import { wellFormed } from '@mpen/valibot-extras';
+*
+* const schema = v.pipe(v.string(), wellFormed());
+* ```
+*
+* @param message - The error message.
+* @returns The Valibot action.
+*/
+function wellFormed(message = "String is not well-formed Unicode") {
+	return attachJsonSchema(v.check((input) => input.isWellFormed(), message), {});
+}
+/**
+* Creates a Valibot schema to validate a well-formed Unicode string.
+*
+* This combines `v.string()` with the [`wellFormed`]{@link wellFormed} validation action.
+*
+* @example
+* ```ts
+* import { unicodeString } from '@mpen/valibot-extras';
+*
+* const schema = unicodeString('Invalid string');
+* ```
+*
+* @param message - The error message.
+* @returns The Valibot schema.
+*/
+function unicodeString(message) {
+	return attachJsonSchema(v.pipe(v.string(), wellFormed(message)), { type: "string" });
+}
+/**
+* Creates a Valibot action to validate the minimum character length of a string (counting Unicode code points).
+*
+* This validator counts UTF-16 surrogate pairs as a single character (matching MySQL's `VARCHAR` length behavior).
+* See also [`maxCharLength`]{@link maxCharLength} and [`charLength`]{@link charLength}.
+*
+* @example
+* ```ts
+* import * as v from 'valibot';
+* import { minCharLength } from '@mpen/valibot-extras';
+*
+* const schema = v.pipe(v.string(), minCharLength(5));
+* ```
+*
+* @param requirement - The minimum character length requirement.
+* @param message - The error message.
+* @returns The Valibot action.
+*/
+function minCharLength(requirement, message) {
+	const action = v.rawCheck(({ dataset, addIssue }) => {
+		if (!dataset.typed || typeof dataset.value !== "string") return;
+		const length = [...dataset.value].length;
+		if (length < requirement) addIssue({
+			message,
+			expected: `>=${requirement}`,
+			received: `${length}`
+		});
+	});
+	return Object.assign(action, {
+		type: "min_length",
+		expects: `>=${requirement}`,
+		requirement,
+		message
+	});
+}
+/**
+* Creates a Valibot action to validate the maximum character length of a string (counting Unicode code points).
+*
+* This validator counts UTF-16 surrogate pairs as a single character (matching MySQL's `VARCHAR` length behavior).
+* See also [`minCharLength`]{@link minCharLength} and [`charLength`]{@link charLength}.
+*
+* @example
+* ```ts
+* import * as v from 'valibot';
+* import { maxCharLength } from '@mpen/valibot-extras';
+*
+* const schema = v.pipe(v.string(), maxCharLength(10));
+* ```
+*
+* @param requirement - The maximum character length requirement.
+* @param message - The error message.
+* @returns The Valibot action.
+*/
+function maxCharLength(requirement, message) {
+	const action = v.rawCheck(({ dataset, addIssue }) => {
+		if (!dataset.typed || typeof dataset.value !== "string") return;
+		const length = [...dataset.value].length;
+		if (length > requirement) addIssue({
+			message,
+			expected: `<=${requirement}`,
+			received: `${length}`
+		});
+	});
+	return Object.assign(action, {
+		type: "max_length",
+		expects: `<=${requirement}`,
+		requirement,
+		message
+	});
+}
+/**
+* Creates a Valibot action to validate the exact character length of a string (counting Unicode code points).
+*
+* This validator counts UTF-16 surrogate pairs as a single character.
+* See also [`minCharLength`]{@link minCharLength} and [`maxCharLength`]{@link maxCharLength}.
+*
+* @example
+* ```ts
+* import * as v from 'valibot';
+* import { charLength } from '@mpen/valibot-extras';
+*
+* const schema = v.pipe(v.string(), charLength(5));
+* ```
+*
+* @param requirement - The exact character length requirement.
+* @param message - The error message.
+* @returns The Valibot action.
+*/
+function charLength(requirement, message) {
+	const action = v.rawCheck(({ dataset, addIssue }) => {
+		if (!dataset.typed || typeof dataset.value !== "string") return;
+		const length = [...dataset.value].length;
+		if (length !== requirement) addIssue({
+			message,
+			expected: `${requirement}`,
+			received: `${length}`
+		});
+	});
+	return Object.assign(action, {
+		type: "length",
+		expects: `${requirement}`,
+		requirement,
+		message
+	});
+}
+//#endregion
+export { attachJsonSchema, charLength, jsonSchemaSymbol, maxCharLength, minCharLength, toJsonSchema, unicodeString, wellFormed };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mpen/valibot-extras",
+  "description": "Extras/extensions for Valibot.",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run --bun tsdown",
+    "dev": "bun run --bun tsdown --watch",
+    "test": "bun test src"
+  },
+  "peerDependencies": {
+    "valibot": "^1.4.1",
+    "@valibot/to-json-schema": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.11.18",
+    "bun-types": "^1.3.13",
+    "tsdown": "^0.21",
+    "typescript": "^6",
+    "valibot": "^1.4.1",
+    "@valibot/to-json-schema": "^1.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mnpenner/npm-packages.git",
+    "directory": "packages/valibot-extras"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts"
+}