@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.11
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/CHANGELOG.md +227 -1
- package/dist/core/cli/dispatch.d.mts +6 -5
- package/dist/core/cli/dispatch.mjs +205 -1
- package/dist/core/cli/help-links.d.mts +0 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.d.mts +81 -8
- package/dist/core/cli/index.mjs +945 -1
- package/dist/core/cli/planner.d.mts +5 -1
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.d.mts +2 -1
- package/dist/core/cli/root-help.mjs +226 -4
- package/dist/core/cli/root-surface.d.mts +12 -1
- package/dist/core/cli/root-surface.mjs +28 -1
- package/dist/core/cli/runtime-preflight.d.mts +14 -2
- package/dist/core/cli/runtime-preflight.mjs +169 -1
- package/dist/core/completion/index.d.mts +0 -1
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +308 -3
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +162 -2
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +358 -2
- package/dist/core/completion/shells/shared.d.mts +13 -2
- package/dist/core/completion/shells/shared.mjs +176 -1
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +251 -2
- package/dist/core/config/index.d.mts +2 -3
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.d.mts +27 -4
- package/dist/core/config/package-json.mjs +386 -3
- package/dist/core/errors/index.d.mts +3 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.d.mts +0 -1
- package/dist/core/execution/index.mjs +201 -1
- package/dist/core/help/ansi.d.mts +11 -5
- package/dist/core/help/ansi.mjs +121 -2
- package/dist/core/help/index.d.mts +22 -3
- package/dist/core/help/index.mjs +341 -7
- package/dist/core/help/theme.d.mts +68 -0
- package/dist/core/help/theme.mjs +46 -0
- package/dist/core/json-schema/index.d.mts +15 -2
- package/dist/core/json-schema/index.mjs +536 -12
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
- package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
- package/dist/core/output/activity.d.mts +0 -1
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.d.mts +4 -5
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -1
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.d.mts +0 -1
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.d.mts +40 -7
- package/dist/core/parse/index.mjs +727 -1
- package/dist/core/prompt/index.d.mts +1 -1
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.d.mts +1 -1
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.d.mts +1 -1
- package/dist/core/resolve/coerce.mjs +336 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/contracts.d.mts +9 -4
- package/dist/core/resolve/errors.d.mts +0 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.d.mts +7 -2
- package/dist/core/resolve/flags.mjs +251 -1
- package/dist/core/resolve/index.d.mts +2 -2
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +4 -2
- package/dist/core/resolve/property.mjs +53 -1
- package/dist/core/schema/activity.d.mts +31 -11
- package/dist/core/schema/arg.d.mts +3 -4
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +26 -6
- package/dist/core/schema/command.mjs +726 -1
- package/dist/core/schema/flag.d.mts +485 -19
- package/dist/core/schema/flag.mjs +705 -1
- package/dist/core/schema/index.d.mts +4 -2
- package/dist/core/schema/middleware.d.mts +4 -3
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.mjs +60 -1
- package/dist/core/schema/prompt.d.mts +6 -3
- package/dist/core/schema/run.d.mts +20 -1
- package/dist/core/schema/string-constraints.d.mts +97 -0
- package/dist/core/schema/string-constraints.mjs +69 -0
- package/dist/core/schema/value-parsers.d.mts +78 -0
- package/dist/core/schema/value-parsers.mjs +142 -0
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.d.mts +0 -31
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +11 -6
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.d.mts +38 -2
- package/dist/runtime/adapter.mjs +87 -1
- package/dist/runtime/auto.d.mts +2 -3
- package/dist/runtime/auto.mjs +45 -1
- package/dist/runtime/deno.d.mts +24 -5
- package/dist/runtime/deno.mjs +262 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/index.d.mts +3 -4
- package/dist/runtime/node.d.mts +8 -2
- package/dist/runtime/node.mjs +220 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.d.mts +4 -4
- package/dist/runtime.mjs +6 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.d.mts +1 -0
- package/dist/testkit.mjs +5 -1
- package/dist/version.d.mts +7 -3
- package/dist/version.mjs +7 -1
- package/dreamcli.schema.json +36 -7
- package/package.json +45 -42
- package/dist/runtime/bun.d.mts +0 -28
- package/dist/runtime/bun.mjs +0 -1
- package/src/core/cli/dispatch.ts +0 -355
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1614
- package/src/core/cli/planner.ts +0 -656
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -342
- package/src/core/cli/root-surface.ts +0 -87
- package/src/core/cli/runtime-preflight.ts +0 -456
- package/src/core/completion/index.ts +0 -138
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -310
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -265
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -563
- package/src/core/json-schema/index.ts +0 -910
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -742
- package/src/core/prompt/index.ts +0 -623
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -500
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -269
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -841
- package/src/core/schema/command.ts +0 -1500
- package/src/core/schema/flag.ts +0 -917
- package/src/core/schema/index.ts +0 -96
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/number-constraints.ts +0 -153
- package/src/core/schema/prompt.ts +0 -171
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -147
- package/src/index.ts +0 -181
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -86
- package/src/runtime/bun.ts +0 -48
- package/src/runtime/deno.ts +0 -367
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -289
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -77
- package/src/runtime.ts +0 -31
- package/src/schema.ts +0 -16
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
package/src/core/schema/run.ts
DELETED
|
@@ -1,198 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Run result type — structured output from command execution.
|
|
3
|
-
*
|
|
4
|
-
* Lives in schema (not testkit) because it describes the execution contract
|
|
5
|
-
* that `ErasedCommand._execute` returns. Both schema and testkit layers
|
|
6
|
-
* reference it without dependency inversion.
|
|
7
|
-
*
|
|
8
|
-
* @module dreamcli/core/schema/run
|
|
9
|
-
*/
|
|
10
|
-
|
|
11
|
-
import type { CLIPlugin } from '#internals/core/cli/plugin.ts';
|
|
12
|
-
import type { CLIError } from '#internals/core/errors/index.ts';
|
|
13
|
-
import type { HelpOptions } from '#internals/core/help/index.ts';
|
|
14
|
-
import type { CapturedOutput, Verbosity } from '#internals/core/output/index.ts';
|
|
15
|
-
import type { PromptEngine, TestAnswer } from '#internals/core/prompt/index.ts';
|
|
16
|
-
import type { ActivityEvent } from './activity.ts';
|
|
17
|
-
import type { CommandMeta, CommandSchema, Out } from './command.ts';
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
* Options accepted by `runCommand()` and internal command execution paths.
|
|
21
|
-
*
|
|
22
|
-
* Every field is optional — sensible defaults are applied. This is the
|
|
23
|
-
* primary process-free execution seam: inject env, config, prompt I/O, and
|
|
24
|
-
* dispatch-layer metadata without touching process state.
|
|
25
|
-
*/
|
|
26
|
-
export interface RunOptions {
|
|
27
|
-
/**
|
|
28
|
-
* Environment variables for flag resolution.
|
|
29
|
-
*
|
|
30
|
-
* Flags with `.env('VAR')` configured resolve from this record
|
|
31
|
-
* when no CLI value is provided (CLI → env → config → prompt → default).
|
|
32
|
-
*/
|
|
33
|
-
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
34
|
-
|
|
35
|
-
/**
|
|
36
|
-
* Configuration object for flag resolution.
|
|
37
|
-
*
|
|
38
|
-
* Flags with `.config('path')` configured resolve from this record
|
|
39
|
-
* when no CLI or env value is provided (CLI → env → config → prompt → default).
|
|
40
|
-
* Config is plain JSON — file loading is the caller's responsibility.
|
|
41
|
-
*/
|
|
42
|
-
readonly config?: Readonly<Record<string, unknown>>;
|
|
43
|
-
|
|
44
|
-
/**
|
|
45
|
-
* Full stdin contents for args configured with `.stdin()`.
|
|
46
|
-
*
|
|
47
|
-
* Lets tests inject piped input without a runtime adapter.
|
|
48
|
-
*/
|
|
49
|
-
readonly stdinData?: string | null;
|
|
50
|
-
|
|
51
|
-
/**
|
|
52
|
-
* Prompt engine for interactive flag resolution.
|
|
53
|
-
*
|
|
54
|
-
* When provided, flags with `.prompt()` configured that have no value
|
|
55
|
-
* after CLI/env/config resolution will be prompted interactively.
|
|
56
|
-
*
|
|
57
|
-
* When absent (and `answers` is also absent), prompting is skipped
|
|
58
|
-
* and resolution falls through to default/required.
|
|
59
|
-
*
|
|
60
|
-
* Takes precedence over `answers` when both are provided.
|
|
61
|
-
*/
|
|
62
|
-
readonly prompter?: PromptEngine;
|
|
63
|
-
|
|
64
|
-
/**
|
|
65
|
-
* Pre-configured prompt answers for testing convenience.
|
|
66
|
-
*
|
|
67
|
-
* When provided, a test prompter is created from these answers via
|
|
68
|
-
* `createTestPrompter(answers)`. Each entry is consumed in order —
|
|
69
|
-
* use `PROMPT_CANCEL` to simulate cancellation.
|
|
70
|
-
*
|
|
71
|
-
* Ignored when an explicit `prompter` is provided.
|
|
72
|
-
*/
|
|
73
|
-
readonly answers?: readonly TestAnswer[];
|
|
74
|
-
|
|
75
|
-
/**
|
|
76
|
-
* Verbosity level for the output channel.
|
|
77
|
-
* @defaultValue `'normal'`
|
|
78
|
-
*/
|
|
79
|
-
readonly verbosity?: Verbosity;
|
|
80
|
-
|
|
81
|
-
/**
|
|
82
|
-
* Enable JSON output mode.
|
|
83
|
-
*
|
|
84
|
-
* When `true`, `log` and `info` messages are redirected to stderr
|
|
85
|
-
* so that stdout is reserved exclusively for structured {@linkcode Out.json | json()} output.
|
|
86
|
-
* Framework-rendered errors are emitted as structured JSON to stdout.
|
|
87
|
-
*
|
|
88
|
-
* @defaultValue `false`
|
|
89
|
-
*/
|
|
90
|
-
readonly jsonMode?: boolean;
|
|
91
|
-
|
|
92
|
-
/**
|
|
93
|
-
* Whether stdout is connected to a TTY.
|
|
94
|
-
*
|
|
95
|
-
* Handlers can check {@linkcode Out.isTTY | out.isTTY} to decide whether to emit decorative
|
|
96
|
-
* output (spinners, progress bars, ANSI codes). Defaults to `false`
|
|
97
|
-
* (safe default for tests — non-TTY until proven otherwise).
|
|
98
|
-
*
|
|
99
|
-
* @defaultValue `false`
|
|
100
|
-
*/
|
|
101
|
-
readonly isTTY?: boolean;
|
|
102
|
-
|
|
103
|
-
/**
|
|
104
|
-
* Output channel override used by live CLI execution.
|
|
105
|
-
*
|
|
106
|
-
* @internal — `CLIBuilder.run()` passes a real output channel so activity renders to
|
|
107
|
-
* the terminal instead of being captured.
|
|
108
|
-
*/
|
|
109
|
-
readonly out?: Out;
|
|
110
|
-
|
|
111
|
-
/**
|
|
112
|
-
* Capture buffers override paired with `out`.
|
|
113
|
-
*
|
|
114
|
-
* @internal — when omitted, `runCommand()` creates empty buffers for the
|
|
115
|
-
* returned {@linkcode RunResult} while writing directly to the provided `out`.
|
|
116
|
-
*/
|
|
117
|
-
readonly captured?: CapturedOutput;
|
|
118
|
-
|
|
119
|
-
/**
|
|
120
|
-
* Help formatting options (width, binName).
|
|
121
|
-
* Used when `--help` is detected.
|
|
122
|
-
*/
|
|
123
|
-
readonly help?: HelpOptions;
|
|
124
|
-
|
|
125
|
-
/**
|
|
126
|
-
* Command schema with propagated flags merged in.
|
|
127
|
-
*
|
|
128
|
-
* When provided, used for parsing and resolution instead of `cmd.schema`.
|
|
129
|
-
* Set by the CLI dispatch layer after collecting propagated flags from
|
|
130
|
-
* the command ancestry path.
|
|
131
|
-
*
|
|
132
|
-
* @internal — set by dispatch layer, not for public use.
|
|
133
|
-
*/
|
|
134
|
-
readonly mergedSchema?: CommandSchema;
|
|
135
|
-
|
|
136
|
-
/**
|
|
137
|
-
* CLI program metadata passed to action handlers and middleware.
|
|
138
|
-
*
|
|
139
|
-
* When provided (by CLI dispatch layer), handlers receive this as `meta`.
|
|
140
|
-
* When absent (standalone `runCommand()`), a minimal meta is constructed
|
|
141
|
-
* from the command's own schema.
|
|
142
|
-
*
|
|
143
|
-
* @internal — populated by CLI dispatch, not for public use.
|
|
144
|
-
*/
|
|
145
|
-
readonly meta?: CommandMeta;
|
|
146
|
-
|
|
147
|
-
/**
|
|
148
|
-
* CLI plugins registered on the parent `CLIBuilder`.
|
|
149
|
-
*
|
|
150
|
-
* @internal — threaded through from CLI dispatch.
|
|
151
|
-
*/
|
|
152
|
-
readonly plugins?: readonly CLIPlugin[];
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
/**
|
|
156
|
-
* Structured result from {@linkcode runCommand}.
|
|
157
|
-
*
|
|
158
|
-
* Contains the exit code, captured stdout/stderr output, recorded
|
|
159
|
-
* {@linkcode ActivityEvent | activity events}, and an `error` field.
|
|
160
|
-
* `error` is `undefined` when execution completed without throwing, even if
|
|
161
|
-
* the handler requested a non-zero status via {@linkcode Out.setExitCode}.
|
|
162
|
-
*
|
|
163
|
-
* @example
|
|
164
|
-
* ```ts
|
|
165
|
-
* const result = await runCommand(greetCmd, ['World']);
|
|
166
|
-
*
|
|
167
|
-
* expect(result.exitCode).toBe(0);
|
|
168
|
-
* expect(result.stdout).toContain('Hello, World!');
|
|
169
|
-
* expect(result.error).toBeUndefined();
|
|
170
|
-
* ```
|
|
171
|
-
*/
|
|
172
|
-
export interface RunResult {
|
|
173
|
-
/** Process exit code. 0 = success. */
|
|
174
|
-
readonly exitCode: number;
|
|
175
|
-
|
|
176
|
-
/** Captured stdout lines (from `out.log` and `out.info`). */
|
|
177
|
-
readonly stdout: readonly string[];
|
|
178
|
-
|
|
179
|
-
/** Captured stderr lines (from `out.warn` and `out.error`). */
|
|
180
|
-
readonly stderr: readonly string[];
|
|
181
|
-
|
|
182
|
-
/**
|
|
183
|
-
* Captured spinner and progress lifecycle events.
|
|
184
|
-
*
|
|
185
|
-
* Recorded separately from stdout/stderr — handlers that call
|
|
186
|
-
* {@linkcode Out.spinner | out.spinner()} or {@linkcode Out.progress | out.progress()} produce events here, enabling
|
|
187
|
-
* targeted assertions on activity lifecycle without parsing text.
|
|
188
|
-
*/
|
|
189
|
-
readonly activity: readonly ActivityEvent[];
|
|
190
|
-
|
|
191
|
-
/**
|
|
192
|
-
* The error that caused a failure, or `undefined` when execution completed.
|
|
193
|
-
* A non-zero `exitCode` can still have no error when a handler calls
|
|
194
|
-
* {@linkcode Out.setExitCode}. {@linkcode CLIError} instances are preserved;
|
|
195
|
-
* unknown errors are wrapped.
|
|
196
|
-
*/
|
|
197
|
-
readonly error: CLIError | undefined;
|
|
198
|
-
}
|
|
@@ -1,109 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Schema DSL — single-source schema definitions with compile-time types
|
|
3
|
-
* and runtime AST.
|
|
4
|
-
*
|
|
5
|
-
* Define a schema once as a string literal. At compile time, the string is
|
|
6
|
-
* parsed into a TypeScript type via {@link Parse}. At runtime, the same
|
|
7
|
-
* string is parsed into an AST ({@link SchemaNode}) for validation,
|
|
8
|
-
* JSON Schema generation, and introspection.
|
|
9
|
-
*
|
|
10
|
-
* ```ts
|
|
11
|
-
* const user = schema('{ name: string; age: number; tags?: string[] }');
|
|
12
|
-
*
|
|
13
|
-
* // Compile-time: inferred as { name: string; age: number; tags?: string[] }
|
|
14
|
-
* const data = user.parse(jsonInput);
|
|
15
|
-
* data.name; // string
|
|
16
|
-
* data.age; // number
|
|
17
|
-
* ```
|
|
18
|
-
*
|
|
19
|
-
* @module dreamcli/core/schema-dsl
|
|
20
|
-
*/
|
|
21
|
-
|
|
22
|
-
import type { Parse } from './parse.ts';
|
|
23
|
-
import type { SchemaNode } from './runtime.ts';
|
|
24
|
-
import { parseSchema, validateNode } from './runtime.ts';
|
|
25
|
-
|
|
26
|
-
// === Schema definition ===
|
|
27
|
-
|
|
28
|
-
/** The result of calling {@link schema}. Bundles source, AST, guard, and parse. */
|
|
29
|
-
interface SchemaDefinition<T extends string> {
|
|
30
|
-
/** The original source string. */
|
|
31
|
-
readonly source: T;
|
|
32
|
-
/** Runtime AST parsed from the source. */
|
|
33
|
-
readonly ast: SchemaNode;
|
|
34
|
-
/**
|
|
35
|
-
* Type guard — returns `true` if `input` matches the schema.
|
|
36
|
-
* Narrows the type to `Parse<T>` in the true branch.
|
|
37
|
-
*/
|
|
38
|
-
guard(input: unknown): input is Parse<T>;
|
|
39
|
-
/**
|
|
40
|
-
* Parse and validate — returns the narrowed value or throws.
|
|
41
|
-
* @throws {TypeError} if the input does not match the schema.
|
|
42
|
-
*/
|
|
43
|
-
parse(input: unknown): Parse<T>;
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* Define a schema from a string literal.
|
|
48
|
-
*
|
|
49
|
-
* @param source - Schema string (e.g. `"{ name: string; age: number }"`).
|
|
50
|
-
* @returns A {@link SchemaDefinition} with compile-time types and runtime validation.
|
|
51
|
-
*
|
|
52
|
-
* @example
|
|
53
|
-
* ```ts
|
|
54
|
-
* const user = schema('{ name: string; age: number; admin?: boolean }');
|
|
55
|
-
*
|
|
56
|
-
* // Type guard
|
|
57
|
-
* if (user.guard(input)) {
|
|
58
|
-
* input.name; // string
|
|
59
|
-
* }
|
|
60
|
-
*
|
|
61
|
-
* // Parse or throw
|
|
62
|
-
* const data = user.parse(input);
|
|
63
|
-
* data.age; // number
|
|
64
|
-
* ```
|
|
65
|
-
*/
|
|
66
|
-
function schema<T extends string>(source: T): SchemaDefinition<T> {
|
|
67
|
-
const ast = parseSchema(source);
|
|
68
|
-
|
|
69
|
-
function guard(input: unknown): input is Parse<T> {
|
|
70
|
-
return validateNode(ast, input);
|
|
71
|
-
}
|
|
72
|
-
|
|
73
|
-
function parse(input: unknown): Parse<T> {
|
|
74
|
-
if (!guard(input)) {
|
|
75
|
-
throw new TypeError(`Value does not match schema: ${source}`);
|
|
76
|
-
}
|
|
77
|
-
return input;
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
return { source, ast, guard, parse };
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
// === Re-exports ===
|
|
84
|
-
|
|
85
|
-
export type { Parse } from './parse.ts';
|
|
86
|
-
export type {
|
|
87
|
-
ArrayNode,
|
|
88
|
-
BooleanNode,
|
|
89
|
-
IntegerNode,
|
|
90
|
-
LiteralFalseNode,
|
|
91
|
-
LiteralNullNode,
|
|
92
|
-
LiteralStringNode,
|
|
93
|
-
LiteralTrueNode,
|
|
94
|
-
LiteralUndefinedNode,
|
|
95
|
-
NeverNode,
|
|
96
|
-
NumberNode,
|
|
97
|
-
ObjectNode,
|
|
98
|
-
PropertyNode,
|
|
99
|
-
RecordNode,
|
|
100
|
-
RefNode,
|
|
101
|
-
SchemaNode,
|
|
102
|
-
StringNode,
|
|
103
|
-
UnionNode,
|
|
104
|
-
UnknownNode,
|
|
105
|
-
} from './runtime.ts';
|
|
106
|
-
export { parseSchema, validateNode } from './runtime.ts';
|
|
107
|
-
export { nodeToJsonSchema } from './to-json-schema.ts';
|
|
108
|
-
export type { SchemaDefinition };
|
|
109
|
-
export { schema };
|
|
@@ -1,262 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Compile-time schema string parser.
|
|
3
|
-
*
|
|
4
|
-
* Parses a string literal like `"{ name: string; age: number }"` into its
|
|
5
|
-
* corresponding TypeScript type at compile time using template literal types
|
|
6
|
-
* and recursive conditional inference.
|
|
7
|
-
*
|
|
8
|
-
* The compile-time parser and the runtime parser in `runtime.ts` implement
|
|
9
|
-
* the same grammar — the type-level version produces TypeScript types while
|
|
10
|
-
* the runtime version produces an AST.
|
|
11
|
-
*
|
|
12
|
-
* @module dreamcli/core/schema-dsl/parse
|
|
13
|
-
*/
|
|
14
|
-
|
|
15
|
-
// === Whitespace handling ===
|
|
16
|
-
|
|
17
|
-
/** Whitespace characters recognized by the parser. */
|
|
18
|
-
type WS = ' ' | '\n' | '\t' | '\r';
|
|
19
|
-
|
|
20
|
-
/** Strip leading whitespace. */
|
|
21
|
-
type TrimLeft<T extends string> = T extends `${WS}${infer R}` ? TrimLeft<R> : T;
|
|
22
|
-
|
|
23
|
-
/** Strip trailing whitespace. */
|
|
24
|
-
type TrimRight<T extends string> = T extends `${infer R}${WS}` ? TrimRight<R> : T;
|
|
25
|
-
|
|
26
|
-
/** Strip leading and trailing whitespace. */
|
|
27
|
-
type Trim<T extends string> = TrimLeft<TrimRight<T>>;
|
|
28
|
-
|
|
29
|
-
// === Character counting for bracket balancing ===
|
|
30
|
-
|
|
31
|
-
/**
|
|
32
|
-
* Single-pass brace depth tracker.
|
|
33
|
-
*
|
|
34
|
-
* Walks the string character by character, pushing to the depth tuple
|
|
35
|
-
* on `{` and popping on `}`. Returns the final depth tuple — an empty
|
|
36
|
-
* tuple means balanced. Returns `false` on underflow (more `}` than `{`).
|
|
37
|
-
*
|
|
38
|
-
* This replaces the Chars + Keep + length approach, which materialized
|
|
39
|
-
* the entire string as a character tuple. Single-pass is O(n) recursion
|
|
40
|
-
* depth instead of O(3n).
|
|
41
|
-
*/
|
|
42
|
-
type TrackDepth<T extends string, D extends unknown[] = []> = T extends `${infer C}${infer R}`
|
|
43
|
-
? C extends '{'
|
|
44
|
-
? TrackDepth<R, [0, ...D]>
|
|
45
|
-
: C extends '}'
|
|
46
|
-
? D extends [unknown, ...infer Rest]
|
|
47
|
-
? TrackDepth<R, Rest>
|
|
48
|
-
: false
|
|
49
|
-
: TrackDepth<R, D>
|
|
50
|
-
: D;
|
|
51
|
-
|
|
52
|
-
/** True when braces are balanced (depth returns to zero without underflow). */
|
|
53
|
-
type Balanced<T extends string> = TrackDepth<T> extends [] ? true : false;
|
|
54
|
-
|
|
55
|
-
// === Balanced splitting ===
|
|
56
|
-
|
|
57
|
-
/**
|
|
58
|
-
* Naively split string T at every occurrence of delimiter D.
|
|
59
|
-
* Does not respect brace nesting — use {@link Rejoin} to rebalance.
|
|
60
|
-
*/
|
|
61
|
-
type RawSplit<T extends string, D extends string> = T extends `${infer A}${D}${infer B}`
|
|
62
|
-
? [A, ...RawSplit<B, D>]
|
|
63
|
-
: [T];
|
|
64
|
-
|
|
65
|
-
/**
|
|
66
|
-
* Walk a tuple of fragments, merging adjacent entries whose cumulative
|
|
67
|
-
* brace count is unbalanced. Delimiter D is reinserted when merging.
|
|
68
|
-
*
|
|
69
|
-
* This is the bracket-balancing trick that makes nested-object parsing
|
|
70
|
-
* practical: split greedily, then glue back together where braces don't
|
|
71
|
-
* match.
|
|
72
|
-
*/
|
|
73
|
-
type Rejoin<T extends string[], D extends string> = T extends [
|
|
74
|
-
infer A extends string,
|
|
75
|
-
infer B extends string,
|
|
76
|
-
...infer R extends string[],
|
|
77
|
-
]
|
|
78
|
-
? Balanced<A> extends true
|
|
79
|
-
? [A, ...Rejoin<[B, ...R], D>]
|
|
80
|
-
: Rejoin<[`${A}${D}${B}`, ...R], D>
|
|
81
|
-
: T;
|
|
82
|
-
|
|
83
|
-
// === Filtering ===
|
|
84
|
-
|
|
85
|
-
/** Remove entries that are empty or whitespace-only after trimming. */
|
|
86
|
-
type NonEmpty<T extends string[]> = T extends [infer H extends string, ...infer R extends string[]]
|
|
87
|
-
? Trim<H> extends ''
|
|
88
|
-
? NonEmpty<R>
|
|
89
|
-
: [H, ...NonEmpty<R>]
|
|
90
|
-
: [];
|
|
91
|
-
|
|
92
|
-
// === Top-level pipe detection ===
|
|
93
|
-
|
|
94
|
-
/**
|
|
95
|
-
* True when the string contains `|` outside of `{}` nesting.
|
|
96
|
-
*
|
|
97
|
-
* Splits at `|`, rebalances with {@link Rejoin}, and checks whether
|
|
98
|
-
* two or more fragments remain. If `|` was only inside braces,
|
|
99
|
-
* rebalancing collapses them back to one fragment.
|
|
100
|
-
*/
|
|
101
|
-
type HasTopLevelPipe<T extends string> =
|
|
102
|
-
Rejoin<RawSplit<T, '|'>, '|'> extends [string, string, ...string[]] ? true : false;
|
|
103
|
-
|
|
104
|
-
// === Flatten intersection into readable object type ===
|
|
105
|
-
|
|
106
|
-
/** Collapse an intersection of object types into a single flat object. */
|
|
107
|
-
type Prettify<T> = { [K in keyof T]: T[K] } & {};
|
|
108
|
-
|
|
109
|
-
// === Primitive mapping ===
|
|
110
|
-
|
|
111
|
-
/** Map a primitive type name to its TypeScript type. */
|
|
112
|
-
type ParsePrimitive<T extends string> = T extends 'string'
|
|
113
|
-
? string
|
|
114
|
-
: T extends 'number'
|
|
115
|
-
? number
|
|
116
|
-
: T extends 'integer'
|
|
117
|
-
? number
|
|
118
|
-
: T extends 'boolean'
|
|
119
|
-
? boolean
|
|
120
|
-
: T extends 'true'
|
|
121
|
-
? true
|
|
122
|
-
: T extends 'false'
|
|
123
|
-
? false
|
|
124
|
-
: T extends 'null'
|
|
125
|
-
? null
|
|
126
|
-
: T extends 'undefined'
|
|
127
|
-
? undefined
|
|
128
|
-
: T extends 'unknown'
|
|
129
|
-
? unknown
|
|
130
|
-
: T extends 'never'
|
|
131
|
-
? never
|
|
132
|
-
: never;
|
|
133
|
-
|
|
134
|
-
// === Union parsing ===
|
|
135
|
-
|
|
136
|
-
/** Parse each tuple entry as a value, producing a tuple of types. */
|
|
137
|
-
type ParseEach<T extends string[]> = T extends [infer H extends string, ...infer R extends string[]]
|
|
138
|
-
? [ParseValue<H>, ...ParseEach<R>]
|
|
139
|
-
: [];
|
|
140
|
-
|
|
141
|
-
/** Collapse a tuple of types into a TypeScript union. */
|
|
142
|
-
type TupleToUnion<T extends unknown[]> = T extends [infer H, ...infer R]
|
|
143
|
-
? H | TupleToUnion<R>
|
|
144
|
-
: never;
|
|
145
|
-
|
|
146
|
-
/** Split at top-level `|`, parse each branch, collapse to union. */
|
|
147
|
-
type ParseUnion<T extends string> = TupleToUnion<
|
|
148
|
-
ParseEach<NonEmpty<Rejoin<RawSplit<T, '|'>, '|'>>>
|
|
149
|
-
>;
|
|
150
|
-
|
|
151
|
-
// === Value parsing ===
|
|
152
|
-
|
|
153
|
-
/**
|
|
154
|
-
* Parse a value type: object, union, array, literal, ref, Record, or primitive.
|
|
155
|
-
*
|
|
156
|
-
* Precedence (highest to lowest):
|
|
157
|
-
* 1. Object — `{...}` wrapping
|
|
158
|
-
* 2. Union — top-level `|` (outside braces)
|
|
159
|
-
* 3. Array — trailing `[]` suffix
|
|
160
|
-
* 4. String literal — `'...'` (maps to literal string type)
|
|
161
|
-
* 5. Reference — `@name` (maps to `unknown` at type level; resolved at runtime)
|
|
162
|
-
* 6. Record — `Record<K, V>` (maps to `Record<string, V>`)
|
|
163
|
-
* 7. Primitive — identifier lookup
|
|
164
|
-
*
|
|
165
|
-
* Union is checked before array so `string | number[]` parses as
|
|
166
|
-
* `string | number[]`, not `(string | number)[]`.
|
|
167
|
-
*/
|
|
168
|
-
type ParseValue<T extends string, V extends string = Trim<T>> = V extends `{${infer Content}}`
|
|
169
|
-
? Prettify<ParseObject<Content>>
|
|
170
|
-
: HasTopLevelPipe<V> extends true
|
|
171
|
-
? ParseUnion<V>
|
|
172
|
-
: V extends `${infer Inner}[]`
|
|
173
|
-
? ParseValue<Inner>[]
|
|
174
|
-
: V extends `'${infer Literal}'`
|
|
175
|
-
? Literal
|
|
176
|
-
: V extends `@${string}`
|
|
177
|
-
? unknown
|
|
178
|
-
: V extends `Record<${string},${infer Val}>`
|
|
179
|
-
? Record<string, ParseValue<Trim<Val>>>
|
|
180
|
-
: ParsePrimitive<V>;
|
|
181
|
-
|
|
182
|
-
// === Property parsing ===
|
|
183
|
-
|
|
184
|
-
/**
|
|
185
|
-
* Parse a single property string like `"name: string"` or `"age?: number"`.
|
|
186
|
-
*
|
|
187
|
-
* Matches the first `:` (leftmost), then checks whether the key ends
|
|
188
|
-
* with `?` to determine optionality. This avoids the trap of matching
|
|
189
|
-
* `?:` inside nested values.
|
|
190
|
-
*/
|
|
191
|
-
type ParseProperty<T extends string> =
|
|
192
|
-
Trim<T> extends `${infer K}:${infer V}`
|
|
193
|
-
? Trim<K> extends `${infer Key}?`
|
|
194
|
-
? { [P in Trim<Key>]?: ParseValue<V> }
|
|
195
|
-
: { [P in Trim<K>]: ParseValue<V> }
|
|
196
|
-
: // biome-ignore lint/complexity/noBannedTypes: identity element for type-level intersection
|
|
197
|
-
{};
|
|
198
|
-
|
|
199
|
-
/** Recursively parse a tuple of property strings and intersect results. */
|
|
200
|
-
type ParseProperties<T extends string[]> = T extends [
|
|
201
|
-
infer H extends string,
|
|
202
|
-
...infer R extends string[],
|
|
203
|
-
]
|
|
204
|
-
? ParseProperty<H> & ParseProperties<R>
|
|
205
|
-
: // biome-ignore lint/complexity/noBannedTypes: identity element for type-level intersection
|
|
206
|
-
{};
|
|
207
|
-
|
|
208
|
-
// === Object parsing ===
|
|
209
|
-
|
|
210
|
-
/**
|
|
211
|
-
* Split content by `;` with bracket balancing, filter empties,
|
|
212
|
-
* parse each property, and intersect into a single object type.
|
|
213
|
-
*/
|
|
214
|
-
type ParseObject<T extends string> = Prettify<
|
|
215
|
-
ParseProperties<NonEmpty<Rejoin<RawSplit<T, ';'>, ';'>>>
|
|
216
|
-
>;
|
|
217
|
-
|
|
218
|
-
// === Entry point ===
|
|
219
|
-
|
|
220
|
-
/**
|
|
221
|
-
* Parse a schema string literal into its TypeScript type.
|
|
222
|
-
*
|
|
223
|
-
* Supports primitives (`string`, `number`, `boolean`, `true`, `false`,
|
|
224
|
-
* `null`, `undefined`, `unknown`, `never`), arrays (`T[]`), objects
|
|
225
|
-
* (`{ key: T; ... }`), optional properties (`key?: T`), unions
|
|
226
|
-
* (`T | U`), and arbitrary nesting.
|
|
227
|
-
*
|
|
228
|
-
* @example
|
|
229
|
-
* ```ts
|
|
230
|
-
* type User = Parse<'{ name: string; age: number; tags?: string[] }'>;
|
|
231
|
-
* // ^? { name: string; age: number; tags?: string[] | undefined }
|
|
232
|
-
*
|
|
233
|
-
* type Status = Parse<'string | true'>;
|
|
234
|
-
* // ^? string | true
|
|
235
|
-
* ```
|
|
236
|
-
*/
|
|
237
|
-
type Parse<T extends string, V extends string = Trim<T>> = V extends `{${infer Content}}`
|
|
238
|
-
? Prettify<ParseObject<Content>>
|
|
239
|
-
: ParseValue<V>;
|
|
240
|
-
|
|
241
|
-
export type {
|
|
242
|
-
Balanced,
|
|
243
|
-
HasTopLevelPipe,
|
|
244
|
-
NonEmpty,
|
|
245
|
-
Parse,
|
|
246
|
-
ParseEach,
|
|
247
|
-
ParseObject,
|
|
248
|
-
ParsePrimitive,
|
|
249
|
-
ParseProperties,
|
|
250
|
-
ParseProperty,
|
|
251
|
-
ParseUnion,
|
|
252
|
-
ParseValue,
|
|
253
|
-
Prettify,
|
|
254
|
-
RawSplit,
|
|
255
|
-
Rejoin,
|
|
256
|
-
TrackDepth,
|
|
257
|
-
Trim,
|
|
258
|
-
TrimLeft,
|
|
259
|
-
TrimRight,
|
|
260
|
-
TupleToUnion,
|
|
261
|
-
WS,
|
|
262
|
-
};
|