@optique/standard-schema 1.2.0-dev.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +20 -0
- package/README.md +100 -0
- package/dist/index.cjs +146 -0
- package/dist/index.d.cts +94 -0
- package/dist/index.d.ts +94 -0
- package/dist/index.js +122 -0
- package/package.json +76 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright 2025–2026 Hong Minhee
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|
6
|
+
this software and associated documentation files (the "Software"), to deal in
|
|
7
|
+
the Software without restriction, including without limitation the rights to
|
|
8
|
+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
|
9
|
+
the Software, and to permit persons to whom the Software is furnished to do so,
|
|
10
|
+
subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|
17
|
+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
18
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
19
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
20
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
@optique/standard-schema
|
|
2
|
+
========================
|
|
3
|
+
|
|
4
|
+
Standard Schema value parsers for Optique. This package lets you use any
|
|
5
|
+
[Standard Schema]-compatible validator as an *@optique/core* value parser.
|
|
6
|
+
|
|
7
|
+
[Standard Schema]: https://standardschema.dev/
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
Installation
|
|
11
|
+
------------
|
|
12
|
+
|
|
13
|
+
~~~~ bash
|
|
14
|
+
deno add jsr:@optique/standard-schema jsr:@optique/run jsr:@optique/core npm:@standard-schema/spec npm:arktype
|
|
15
|
+
npm add @optique/standard-schema @optique/run @optique/core @standard-schema/spec arktype
|
|
16
|
+
pnpm add @optique/standard-schema @optique/run @optique/core @standard-schema/spec arktype
|
|
17
|
+
yarn add @optique/standard-schema @optique/run @optique/core @standard-schema/spec arktype
|
|
18
|
+
bun add @optique/standard-schema @optique/run @optique/core @standard-schema/spec arktype
|
|
19
|
+
~~~~
|
|
20
|
+
|
|
21
|
+
Replace `arktype` with any Standard Schema-compatible library you want to use.
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
Quick example
|
|
25
|
+
-------------
|
|
26
|
+
|
|
27
|
+
The following example validates an email address with an ArkType schema through
|
|
28
|
+
the generic `standardSchema()` adapter.
|
|
29
|
+
|
|
30
|
+
~~~~ typescript
|
|
31
|
+
import { object } from "@optique/core/constructs";
|
|
32
|
+
import { option } from "@optique/core/primitives";
|
|
33
|
+
import { run } from "@optique/run";
|
|
34
|
+
import { standardSchema } from "@optique/standard-schema";
|
|
35
|
+
import { type } from "arktype";
|
|
36
|
+
|
|
37
|
+
const cli = run(
|
|
38
|
+
object({
|
|
39
|
+
email: option("--email",
|
|
40
|
+
standardSchema(type("string.email"), {
|
|
41
|
+
placeholder: "",
|
|
42
|
+
metavar: "EMAIL",
|
|
43
|
+
}),
|
|
44
|
+
),
|
|
45
|
+
}),
|
|
46
|
+
);
|
|
47
|
+
|
|
48
|
+
console.log(`Welcome, ${cli.email}!`);
|
|
49
|
+
~~~~
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
Async schemas
|
|
53
|
+
-------------
|
|
54
|
+
|
|
55
|
+
Use `standardSchemaAsync()` when the validator may perform async work:
|
|
56
|
+
|
|
57
|
+
~~~~ typescript
|
|
58
|
+
import { option } from "@optique/core/primitives";
|
|
59
|
+
import { runAsync } from "@optique/run";
|
|
60
|
+
import { standardSchemaAsync } from "@optique/standard-schema";
|
|
61
|
+
import type { StandardSchemaV1 } from "@standard-schema/spec";
|
|
62
|
+
|
|
63
|
+
const apiKeySchema: StandardSchemaV1<unknown, string> = {
|
|
64
|
+
"~standard": {
|
|
65
|
+
version: 1,
|
|
66
|
+
vendor: "example",
|
|
67
|
+
async validate(value) {
|
|
68
|
+
if (typeof value === "string" && value.startsWith("live_")) {
|
|
69
|
+
return { value };
|
|
70
|
+
}
|
|
71
|
+
return { issues: [{ message: "Unknown API key." }] };
|
|
72
|
+
},
|
|
73
|
+
},
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
const apiKey = option("--api-key",
|
|
77
|
+
standardSchemaAsync(apiKeySchema, {
|
|
78
|
+
placeholder: "",
|
|
79
|
+
metavar: "API_KEY",
|
|
80
|
+
}),
|
|
81
|
+
);
|
|
82
|
+
|
|
83
|
+
const key = await runAsync(apiKey);
|
|
84
|
+
~~~~
|
|
85
|
+
|
|
86
|
+
The synchronous `standardSchema()` helper rejects async validation results and
|
|
87
|
+
asks you to use `standardSchemaAsync()` instead.
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
Dedicated adapters
|
|
91
|
+
------------------
|
|
92
|
+
|
|
93
|
+
Standard Schema intentionally exposes validation results, not library-specific
|
|
94
|
+
metadata. This package therefore stays conservative: it does not infer choices,
|
|
95
|
+
completion suggestions, Boolean CLI literals, or specialized metavars from the
|
|
96
|
+
underlying schema.
|
|
97
|
+
|
|
98
|
+
Use *@optique/zod* or *@optique/valibot* when you want richer behavior for
|
|
99
|
+
those libraries. Use *@optique/standard-schema* when portability matters, or
|
|
100
|
+
when your schema library does not have a dedicated Optique adapter.
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
//#region rolldown:runtime
|
|
2
|
+
var __create = Object.create;
|
|
3
|
+
var __defProp = Object.defineProperty;
|
|
4
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
5
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
6
|
+
var __getProtoOf = Object.getPrototypeOf;
|
|
7
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
8
|
+
var __copyProps = (to, from, except, desc) => {
|
|
9
|
+
if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
|
|
10
|
+
key = keys[i];
|
|
11
|
+
if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
|
|
12
|
+
get: ((k) => from[k]).bind(null, key),
|
|
13
|
+
enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
|
|
14
|
+
});
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
|
|
19
|
+
value: mod,
|
|
20
|
+
enumerable: true
|
|
21
|
+
}) : target, mod));
|
|
22
|
+
|
|
23
|
+
//#endregion
|
|
24
|
+
const __optique_core_message = __toESM(require("@optique/core/message"));
|
|
25
|
+
const __optique_core_nonempty = __toESM(require("@optique/core/nonempty"));
|
|
26
|
+
|
|
27
|
+
//#region src/index.ts
|
|
28
|
+
function validateOptions(functionName, options) {
|
|
29
|
+
if (options == null || typeof options !== "object" || Array.isArray(options)) throw new TypeError(`${functionName}() requires an options object with a placeholder property.`);
|
|
30
|
+
if (!("placeholder" in options)) throw new TypeError(`${functionName}() options must include a placeholder property.`);
|
|
31
|
+
}
|
|
32
|
+
function isPromiseLike(value) {
|
|
33
|
+
return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
|
|
34
|
+
}
|
|
35
|
+
function formatValue(value, format) {
|
|
36
|
+
if (format) return format(value);
|
|
37
|
+
if (value instanceof Date) return Number.isNaN(value.getTime()) ? String(value) : value.toISOString();
|
|
38
|
+
if (typeof value !== "object" || value === null) return String(value);
|
|
39
|
+
if (Array.isArray(value)) return String(value);
|
|
40
|
+
const str = String(value);
|
|
41
|
+
if (str !== "[object Object]") return str;
|
|
42
|
+
const proto = Object.getPrototypeOf(value);
|
|
43
|
+
if (proto === Object.prototype || proto === null) try {
|
|
44
|
+
return JSON.stringify(value) ?? str;
|
|
45
|
+
} catch {}
|
|
46
|
+
return str;
|
|
47
|
+
}
|
|
48
|
+
function validationFailure(issues, input, error) {
|
|
49
|
+
if (error) return {
|
|
50
|
+
success: false,
|
|
51
|
+
error: typeof error === "function" ? error(issues, input) : error
|
|
52
|
+
};
|
|
53
|
+
return {
|
|
54
|
+
success: false,
|
|
55
|
+
error: __optique_core_message.message`${(0, __optique_core_message.text)(issues[0]?.message ?? "Validation failed")}`
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
function processValidationResult(result, input, options) {
|
|
59
|
+
if (result.issues) return validationFailure(result.issues, input, options.errors?.schemaError);
|
|
60
|
+
return {
|
|
61
|
+
success: true,
|
|
62
|
+
value: result.value
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Creates a value parser from a Standard Schema-compatible validator.
|
|
67
|
+
*
|
|
68
|
+
* The returned parser validates CLI argument strings with
|
|
69
|
+
* `schema["~standard"].validate(input)`. Standard Schema does not expose
|
|
70
|
+
* library-specific metadata such as enum choices, Boolean parser shape, or
|
|
71
|
+
* preferred metavars, so this generic adapter stays conservative. Use
|
|
72
|
+
* dedicated adapters such as *@optique/zod* or *@optique/valibot* when their
|
|
73
|
+
* richer CLI behavior is useful.
|
|
74
|
+
*
|
|
75
|
+
* @template T The output type of the Standard Schema validator.
|
|
76
|
+
* @param schema A Standard Schema-compatible validator.
|
|
77
|
+
* @param options Configuration for the parser, including a required
|
|
78
|
+
* `placeholder` value used during deferred prompt resolution.
|
|
79
|
+
* @returns A value parser that validates inputs using the provided schema.
|
|
80
|
+
*
|
|
81
|
+
* @throws {TypeError} If `options` is missing, not an object, or does not
|
|
82
|
+
* include `placeholder`.
|
|
83
|
+
* @throws {TypeError} If the resolved `metavar` is an empty string.
|
|
84
|
+
* @throws {TypeError} If the validator returns a promise during parsing.
|
|
85
|
+
* @since 1.2.0
|
|
86
|
+
*/
|
|
87
|
+
function standardSchema(schema, options) {
|
|
88
|
+
validateOptions("standardSchema", options);
|
|
89
|
+
const metavar = options.metavar ?? "VALUE";
|
|
90
|
+
(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
|
|
91
|
+
const parser = {
|
|
92
|
+
mode: "sync",
|
|
93
|
+
metavar,
|
|
94
|
+
placeholder: options.placeholder,
|
|
95
|
+
parse(input) {
|
|
96
|
+
const result = schema["~standard"].validate(input);
|
|
97
|
+
if (isPromiseLike(result)) throw new TypeError("Async Standard Schema validators are not supported by standardSchema(). Use standardSchemaAsync() instead.");
|
|
98
|
+
return processValidationResult(result, input, options);
|
|
99
|
+
},
|
|
100
|
+
format(value) {
|
|
101
|
+
return formatValue(value, options.format);
|
|
102
|
+
}
|
|
103
|
+
};
|
|
104
|
+
return parser;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* Creates an async value parser from a Standard Schema-compatible validator.
|
|
108
|
+
*
|
|
109
|
+
* Use this helper when the validator may return a promise from
|
|
110
|
+
* `schema["~standard"].validate(input)`, such as schemas with asynchronous
|
|
111
|
+
* refinements or checks. Synchronous validators are also accepted.
|
|
112
|
+
*
|
|
113
|
+
* @template T The output type of the Standard Schema validator.
|
|
114
|
+
* @param schema A Standard Schema-compatible validator.
|
|
115
|
+
* @param options Configuration for the parser, including a required
|
|
116
|
+
* `placeholder` value used during deferred prompt resolution.
|
|
117
|
+
* @returns An async value parser that validates inputs using the provided
|
|
118
|
+
* schema.
|
|
119
|
+
*
|
|
120
|
+
* @throws {TypeError} If `options` is missing, not an object, or does not
|
|
121
|
+
* include `placeholder`.
|
|
122
|
+
* @throws {TypeError} If the resolved `metavar` is an empty string.
|
|
123
|
+
* @since 1.2.0
|
|
124
|
+
*/
|
|
125
|
+
function standardSchemaAsync(schema, options) {
|
|
126
|
+
validateOptions("standardSchemaAsync", options);
|
|
127
|
+
const metavar = options.metavar ?? "VALUE";
|
|
128
|
+
(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
|
|
129
|
+
const parser = {
|
|
130
|
+
mode: "async",
|
|
131
|
+
metavar,
|
|
132
|
+
placeholder: options.placeholder,
|
|
133
|
+
async parse(input) {
|
|
134
|
+
const result = await schema["~standard"].validate(input);
|
|
135
|
+
return processValidationResult(result, input, options);
|
|
136
|
+
},
|
|
137
|
+
format(value) {
|
|
138
|
+
return formatValue(value, options.format);
|
|
139
|
+
}
|
|
140
|
+
};
|
|
141
|
+
return parser;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
//#endregion
|
|
145
|
+
exports.standardSchema = standardSchema;
|
|
146
|
+
exports.standardSchemaAsync = standardSchemaAsync;
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { StandardSchemaV1 } from "@standard-schema/spec";
|
|
2
|
+
import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
|
|
3
|
+
import { Message } from "@optique/core/message";
|
|
4
|
+
|
|
5
|
+
//#region src/index.d.ts
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Options for creating a Standard Schema value parser.
|
|
9
|
+
*
|
|
10
|
+
* @template T The output type of the Standard Schema validator.
|
|
11
|
+
* @since 1.2.0
|
|
12
|
+
*/
|
|
13
|
+
interface StandardSchemaParserOptions<T = unknown> {
|
|
14
|
+
/**
|
|
15
|
+
* The metavariable name for this parser. This is used in help messages to
|
|
16
|
+
* indicate what kind of value this parser expects. Usually a single
|
|
17
|
+
* word in uppercase, like `VALUE` or `SCHEMA`.
|
|
18
|
+
* @default `"VALUE"`
|
|
19
|
+
*/
|
|
20
|
+
readonly metavar?: NonEmptyString;
|
|
21
|
+
/**
|
|
22
|
+
* A phase-one stand-in value of type `T` used during deferred prompt
|
|
23
|
+
* resolution. Because the output type of a Standard Schema validator cannot
|
|
24
|
+
* be inferred to a concrete default, callers must provide this explicitly.
|
|
25
|
+
*/
|
|
26
|
+
readonly placeholder: T;
|
|
27
|
+
/**
|
|
28
|
+
* Custom formatter for displaying parsed values in help messages.
|
|
29
|
+
* When not provided, the default formatter is used: primitives use
|
|
30
|
+
* `String()`, valid `Date` values use `.toISOString()`, and plain
|
|
31
|
+
* objects use `JSON.stringify()` when possible. All other objects use
|
|
32
|
+
* `String()`.
|
|
33
|
+
*
|
|
34
|
+
* @param value The parsed value to format.
|
|
35
|
+
* @returns A string representation of the value.
|
|
36
|
+
*/
|
|
37
|
+
readonly format?: (value: T) => string;
|
|
38
|
+
/**
|
|
39
|
+
* Custom error messages for Standard Schema validation failures.
|
|
40
|
+
*/
|
|
41
|
+
readonly errors?: {
|
|
42
|
+
/**
|
|
43
|
+
* Custom error message when input fails Standard Schema validation. Can be
|
|
44
|
+
* a static message or a function that receives the Standard Schema issues
|
|
45
|
+
* and input string.
|
|
46
|
+
*/
|
|
47
|
+
readonly schemaError?: Message | ((issues: readonly StandardSchemaV1.Issue[], input: string) => Message);
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Creates a value parser from a Standard Schema-compatible validator.
|
|
52
|
+
*
|
|
53
|
+
* The returned parser validates CLI argument strings with
|
|
54
|
+
* `schema["~standard"].validate(input)`. Standard Schema does not expose
|
|
55
|
+
* library-specific metadata such as enum choices, Boolean parser shape, or
|
|
56
|
+
* preferred metavars, so this generic adapter stays conservative. Use
|
|
57
|
+
* dedicated adapters such as *@optique/zod* or *@optique/valibot* when their
|
|
58
|
+
* richer CLI behavior is useful.
|
|
59
|
+
*
|
|
60
|
+
* @template T The output type of the Standard Schema validator.
|
|
61
|
+
* @param schema A Standard Schema-compatible validator.
|
|
62
|
+
* @param options Configuration for the parser, including a required
|
|
63
|
+
* `placeholder` value used during deferred prompt resolution.
|
|
64
|
+
* @returns A value parser that validates inputs using the provided schema.
|
|
65
|
+
*
|
|
66
|
+
* @throws {TypeError} If `options` is missing, not an object, or does not
|
|
67
|
+
* include `placeholder`.
|
|
68
|
+
* @throws {TypeError} If the resolved `metavar` is an empty string.
|
|
69
|
+
* @throws {TypeError} If the validator returns a promise during parsing.
|
|
70
|
+
* @since 1.2.0
|
|
71
|
+
*/
|
|
72
|
+
declare function standardSchema<T>(schema: StandardSchemaV1<unknown, T>, options: StandardSchemaParserOptions<T>): ValueParser<"sync", T>;
|
|
73
|
+
/**
|
|
74
|
+
* Creates an async value parser from a Standard Schema-compatible validator.
|
|
75
|
+
*
|
|
76
|
+
* Use this helper when the validator may return a promise from
|
|
77
|
+
* `schema["~standard"].validate(input)`, such as schemas with asynchronous
|
|
78
|
+
* refinements or checks. Synchronous validators are also accepted.
|
|
79
|
+
*
|
|
80
|
+
* @template T The output type of the Standard Schema validator.
|
|
81
|
+
* @param schema A Standard Schema-compatible validator.
|
|
82
|
+
* @param options Configuration for the parser, including a required
|
|
83
|
+
* `placeholder` value used during deferred prompt resolution.
|
|
84
|
+
* @returns An async value parser that validates inputs using the provided
|
|
85
|
+
* schema.
|
|
86
|
+
*
|
|
87
|
+
* @throws {TypeError} If `options` is missing, not an object, or does not
|
|
88
|
+
* include `placeholder`.
|
|
89
|
+
* @throws {TypeError} If the resolved `metavar` is an empty string.
|
|
90
|
+
* @since 1.2.0
|
|
91
|
+
*/
|
|
92
|
+
declare function standardSchemaAsync<T>(schema: StandardSchemaV1<unknown, T>, options: StandardSchemaParserOptions<T>): ValueParser<"async", T>;
|
|
93
|
+
//#endregion
|
|
94
|
+
export { StandardSchemaParserOptions, standardSchema, standardSchemaAsync };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { Message } from "@optique/core/message";
|
|
2
|
+
import { StandardSchemaV1 } from "@standard-schema/spec";
|
|
3
|
+
import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
|
|
4
|
+
|
|
5
|
+
//#region src/index.d.ts
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Options for creating a Standard Schema value parser.
|
|
9
|
+
*
|
|
10
|
+
* @template T The output type of the Standard Schema validator.
|
|
11
|
+
* @since 1.2.0
|
|
12
|
+
*/
|
|
13
|
+
interface StandardSchemaParserOptions<T = unknown> {
|
|
14
|
+
/**
|
|
15
|
+
* The metavariable name for this parser. This is used in help messages to
|
|
16
|
+
* indicate what kind of value this parser expects. Usually a single
|
|
17
|
+
* word in uppercase, like `VALUE` or `SCHEMA`.
|
|
18
|
+
* @default `"VALUE"`
|
|
19
|
+
*/
|
|
20
|
+
readonly metavar?: NonEmptyString;
|
|
21
|
+
/**
|
|
22
|
+
* A phase-one stand-in value of type `T` used during deferred prompt
|
|
23
|
+
* resolution. Because the output type of a Standard Schema validator cannot
|
|
24
|
+
* be inferred to a concrete default, callers must provide this explicitly.
|
|
25
|
+
*/
|
|
26
|
+
readonly placeholder: T;
|
|
27
|
+
/**
|
|
28
|
+
* Custom formatter for displaying parsed values in help messages.
|
|
29
|
+
* When not provided, the default formatter is used: primitives use
|
|
30
|
+
* `String()`, valid `Date` values use `.toISOString()`, and plain
|
|
31
|
+
* objects use `JSON.stringify()` when possible. All other objects use
|
|
32
|
+
* `String()`.
|
|
33
|
+
*
|
|
34
|
+
* @param value The parsed value to format.
|
|
35
|
+
* @returns A string representation of the value.
|
|
36
|
+
*/
|
|
37
|
+
readonly format?: (value: T) => string;
|
|
38
|
+
/**
|
|
39
|
+
* Custom error messages for Standard Schema validation failures.
|
|
40
|
+
*/
|
|
41
|
+
readonly errors?: {
|
|
42
|
+
/**
|
|
43
|
+
* Custom error message when input fails Standard Schema validation. Can be
|
|
44
|
+
* a static message or a function that receives the Standard Schema issues
|
|
45
|
+
* and input string.
|
|
46
|
+
*/
|
|
47
|
+
readonly schemaError?: Message | ((issues: readonly StandardSchemaV1.Issue[], input: string) => Message);
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Creates a value parser from a Standard Schema-compatible validator.
|
|
52
|
+
*
|
|
53
|
+
* The returned parser validates CLI argument strings with
|
|
54
|
+
* `schema["~standard"].validate(input)`. Standard Schema does not expose
|
|
55
|
+
* library-specific metadata such as enum choices, Boolean parser shape, or
|
|
56
|
+
* preferred metavars, so this generic adapter stays conservative. Use
|
|
57
|
+
* dedicated adapters such as *@optique/zod* or *@optique/valibot* when their
|
|
58
|
+
* richer CLI behavior is useful.
|
|
59
|
+
*
|
|
60
|
+
* @template T The output type of the Standard Schema validator.
|
|
61
|
+
* @param schema A Standard Schema-compatible validator.
|
|
62
|
+
* @param options Configuration for the parser, including a required
|
|
63
|
+
* `placeholder` value used during deferred prompt resolution.
|
|
64
|
+
* @returns A value parser that validates inputs using the provided schema.
|
|
65
|
+
*
|
|
66
|
+
* @throws {TypeError} If `options` is missing, not an object, or does not
|
|
67
|
+
* include `placeholder`.
|
|
68
|
+
* @throws {TypeError} If the resolved `metavar` is an empty string.
|
|
69
|
+
* @throws {TypeError} If the validator returns a promise during parsing.
|
|
70
|
+
* @since 1.2.0
|
|
71
|
+
*/
|
|
72
|
+
declare function standardSchema<T>(schema: StandardSchemaV1<unknown, T>, options: StandardSchemaParserOptions<T>): ValueParser<"sync", T>;
|
|
73
|
+
/**
|
|
74
|
+
* Creates an async value parser from a Standard Schema-compatible validator.
|
|
75
|
+
*
|
|
76
|
+
* Use this helper when the validator may return a promise from
|
|
77
|
+
* `schema["~standard"].validate(input)`, such as schemas with asynchronous
|
|
78
|
+
* refinements or checks. Synchronous validators are also accepted.
|
|
79
|
+
*
|
|
80
|
+
* @template T The output type of the Standard Schema validator.
|
|
81
|
+
* @param schema A Standard Schema-compatible validator.
|
|
82
|
+
* @param options Configuration for the parser, including a required
|
|
83
|
+
* `placeholder` value used during deferred prompt resolution.
|
|
84
|
+
* @returns An async value parser that validates inputs using the provided
|
|
85
|
+
* schema.
|
|
86
|
+
*
|
|
87
|
+
* @throws {TypeError} If `options` is missing, not an object, or does not
|
|
88
|
+
* include `placeholder`.
|
|
89
|
+
* @throws {TypeError} If the resolved `metavar` is an empty string.
|
|
90
|
+
* @since 1.2.0
|
|
91
|
+
*/
|
|
92
|
+
declare function standardSchemaAsync<T>(schema: StandardSchemaV1<unknown, T>, options: StandardSchemaParserOptions<T>): ValueParser<"async", T>;
|
|
93
|
+
//#endregion
|
|
94
|
+
export { StandardSchemaParserOptions, standardSchema, standardSchemaAsync };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import { message, text } from "@optique/core/message";
|
|
2
|
+
import { ensureNonEmptyString } from "@optique/core/nonempty";
|
|
3
|
+
|
|
4
|
+
//#region src/index.ts
|
|
5
|
+
function validateOptions(functionName, options) {
|
|
6
|
+
if (options == null || typeof options !== "object" || Array.isArray(options)) throw new TypeError(`${functionName}() requires an options object with a placeholder property.`);
|
|
7
|
+
if (!("placeholder" in options)) throw new TypeError(`${functionName}() options must include a placeholder property.`);
|
|
8
|
+
}
|
|
9
|
+
function isPromiseLike(value) {
|
|
10
|
+
return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
|
|
11
|
+
}
|
|
12
|
+
function formatValue(value, format) {
|
|
13
|
+
if (format) return format(value);
|
|
14
|
+
if (value instanceof Date) return Number.isNaN(value.getTime()) ? String(value) : value.toISOString();
|
|
15
|
+
if (typeof value !== "object" || value === null) return String(value);
|
|
16
|
+
if (Array.isArray(value)) return String(value);
|
|
17
|
+
const str = String(value);
|
|
18
|
+
if (str !== "[object Object]") return str;
|
|
19
|
+
const proto = Object.getPrototypeOf(value);
|
|
20
|
+
if (proto === Object.prototype || proto === null) try {
|
|
21
|
+
return JSON.stringify(value) ?? str;
|
|
22
|
+
} catch {}
|
|
23
|
+
return str;
|
|
24
|
+
}
|
|
25
|
+
function validationFailure(issues, input, error) {
|
|
26
|
+
if (error) return {
|
|
27
|
+
success: false,
|
|
28
|
+
error: typeof error === "function" ? error(issues, input) : error
|
|
29
|
+
};
|
|
30
|
+
return {
|
|
31
|
+
success: false,
|
|
32
|
+
error: message`${text(issues[0]?.message ?? "Validation failed")}`
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
function processValidationResult(result, input, options) {
|
|
36
|
+
if (result.issues) return validationFailure(result.issues, input, options.errors?.schemaError);
|
|
37
|
+
return {
|
|
38
|
+
success: true,
|
|
39
|
+
value: result.value
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Creates a value parser from a Standard Schema-compatible validator.
|
|
44
|
+
*
|
|
45
|
+
* The returned parser validates CLI argument strings with
|
|
46
|
+
* `schema["~standard"].validate(input)`. Standard Schema does not expose
|
|
47
|
+
* library-specific metadata such as enum choices, Boolean parser shape, or
|
|
48
|
+
* preferred metavars, so this generic adapter stays conservative. Use
|
|
49
|
+
* dedicated adapters such as *@optique/zod* or *@optique/valibot* when their
|
|
50
|
+
* richer CLI behavior is useful.
|
|
51
|
+
*
|
|
52
|
+
* @template T The output type of the Standard Schema validator.
|
|
53
|
+
* @param schema A Standard Schema-compatible validator.
|
|
54
|
+
* @param options Configuration for the parser, including a required
|
|
55
|
+
* `placeholder` value used during deferred prompt resolution.
|
|
56
|
+
* @returns A value parser that validates inputs using the provided schema.
|
|
57
|
+
*
|
|
58
|
+
* @throws {TypeError} If `options` is missing, not an object, or does not
|
|
59
|
+
* include `placeholder`.
|
|
60
|
+
* @throws {TypeError} If the resolved `metavar` is an empty string.
|
|
61
|
+
* @throws {TypeError} If the validator returns a promise during parsing.
|
|
62
|
+
* @since 1.2.0
|
|
63
|
+
*/
|
|
64
|
+
function standardSchema(schema, options) {
|
|
65
|
+
validateOptions("standardSchema", options);
|
|
66
|
+
const metavar = options.metavar ?? "VALUE";
|
|
67
|
+
ensureNonEmptyString(metavar);
|
|
68
|
+
const parser = {
|
|
69
|
+
mode: "sync",
|
|
70
|
+
metavar,
|
|
71
|
+
placeholder: options.placeholder,
|
|
72
|
+
parse(input) {
|
|
73
|
+
const result = schema["~standard"].validate(input);
|
|
74
|
+
if (isPromiseLike(result)) throw new TypeError("Async Standard Schema validators are not supported by standardSchema(). Use standardSchemaAsync() instead.");
|
|
75
|
+
return processValidationResult(result, input, options);
|
|
76
|
+
},
|
|
77
|
+
format(value) {
|
|
78
|
+
return formatValue(value, options.format);
|
|
79
|
+
}
|
|
80
|
+
};
|
|
81
|
+
return parser;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Creates an async value parser from a Standard Schema-compatible validator.
|
|
85
|
+
*
|
|
86
|
+
* Use this helper when the validator may return a promise from
|
|
87
|
+
* `schema["~standard"].validate(input)`, such as schemas with asynchronous
|
|
88
|
+
* refinements or checks. Synchronous validators are also accepted.
|
|
89
|
+
*
|
|
90
|
+
* @template T The output type of the Standard Schema validator.
|
|
91
|
+
* @param schema A Standard Schema-compatible validator.
|
|
92
|
+
* @param options Configuration for the parser, including a required
|
|
93
|
+
* `placeholder` value used during deferred prompt resolution.
|
|
94
|
+
* @returns An async value parser that validates inputs using the provided
|
|
95
|
+
* schema.
|
|
96
|
+
*
|
|
97
|
+
* @throws {TypeError} If `options` is missing, not an object, or does not
|
|
98
|
+
* include `placeholder`.
|
|
99
|
+
* @throws {TypeError} If the resolved `metavar` is an empty string.
|
|
100
|
+
* @since 1.2.0
|
|
101
|
+
*/
|
|
102
|
+
function standardSchemaAsync(schema, options) {
|
|
103
|
+
validateOptions("standardSchemaAsync", options);
|
|
104
|
+
const metavar = options.metavar ?? "VALUE";
|
|
105
|
+
ensureNonEmptyString(metavar);
|
|
106
|
+
const parser = {
|
|
107
|
+
mode: "async",
|
|
108
|
+
metavar,
|
|
109
|
+
placeholder: options.placeholder,
|
|
110
|
+
async parse(input) {
|
|
111
|
+
const result = await schema["~standard"].validate(input);
|
|
112
|
+
return processValidationResult(result, input, options);
|
|
113
|
+
},
|
|
114
|
+
format(value) {
|
|
115
|
+
return formatValue(value, options.format);
|
|
116
|
+
}
|
|
117
|
+
};
|
|
118
|
+
return parser;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
//#endregion
|
|
122
|
+
export { standardSchema, standardSchemaAsync };
|
package/package.json
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@optique/standard-schema",
|
|
3
|
+
"version": "1.2.0-dev.0",
|
|
4
|
+
"description": "Standard Schema value parsers for Optique",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"CLI",
|
|
7
|
+
"command-line",
|
|
8
|
+
"commandline",
|
|
9
|
+
"parser",
|
|
10
|
+
"standard-schema",
|
|
11
|
+
"validation"
|
|
12
|
+
],
|
|
13
|
+
"license": "MIT",
|
|
14
|
+
"author": {
|
|
15
|
+
"name": "Hong Minhee",
|
|
16
|
+
"email": "hong@minhee.org",
|
|
17
|
+
"url": "https://hongminhee.org/"
|
|
18
|
+
},
|
|
19
|
+
"homepage": "https://optique.dev/",
|
|
20
|
+
"repository": {
|
|
21
|
+
"type": "git",
|
|
22
|
+
"url": "git+https://github.com/dahlia/optique.git",
|
|
23
|
+
"directory": "packages/standard-schema/"
|
|
24
|
+
},
|
|
25
|
+
"bugs": {
|
|
26
|
+
"url": "https://github.com/dahlia/optique/issues"
|
|
27
|
+
},
|
|
28
|
+
"funding": [
|
|
29
|
+
"https://github.com/sponsors/dahlia"
|
|
30
|
+
],
|
|
31
|
+
"engines": {
|
|
32
|
+
"node": ">=20.0.0",
|
|
33
|
+
"bun": ">=1.2.0",
|
|
34
|
+
"deno": ">=2.3.0"
|
|
35
|
+
},
|
|
36
|
+
"files": [
|
|
37
|
+
"dist/",
|
|
38
|
+
"package.json",
|
|
39
|
+
"README.md"
|
|
40
|
+
],
|
|
41
|
+
"type": "module",
|
|
42
|
+
"module": "./dist/index.js",
|
|
43
|
+
"main": "./dist/index.cjs",
|
|
44
|
+
"types": "./dist/index.d.ts",
|
|
45
|
+
"exports": {
|
|
46
|
+
".": {
|
|
47
|
+
"types": {
|
|
48
|
+
"import": "./dist/index.d.ts",
|
|
49
|
+
"require": "./dist/index.d.cts"
|
|
50
|
+
},
|
|
51
|
+
"import": "./dist/index.js",
|
|
52
|
+
"require": "./dist/index.cjs"
|
|
53
|
+
}
|
|
54
|
+
},
|
|
55
|
+
"sideEffects": false,
|
|
56
|
+
"peerDependencies": {
|
|
57
|
+
"@standard-schema/spec": "^1.1.0"
|
|
58
|
+
},
|
|
59
|
+
"dependencies": {
|
|
60
|
+
"@optique/core": "1.2.0"
|
|
61
|
+
},
|
|
62
|
+
"devDependencies": {
|
|
63
|
+
"@standard-schema/spec": "^1.1.0",
|
|
64
|
+
"@types/node": "^24.0.0",
|
|
65
|
+
"tsdown": "^0.13.0",
|
|
66
|
+
"typescript": "^5.8.3"
|
|
67
|
+
},
|
|
68
|
+
"scripts": {
|
|
69
|
+
"build": "tsdown",
|
|
70
|
+
"prepublish": "tsdown",
|
|
71
|
+
"test": "node --test",
|
|
72
|
+
"test:bun": "bun test",
|
|
73
|
+
"test:deno": "deno test",
|
|
74
|
+
"test-all": "tsdown && node --test && bun test && deno test"
|
|
75
|
+
}
|
|
76
|
+
}
|