@ykdz/template 0.0.37 → 0.0.40

package/node_modules/@valibot/to-json-schema/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Fabian Hiller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/node_modules/@valibot/to-json-schema/README.md

@@ -0,0 +1,475 @@
+# Valibot to JSON Schema
+
+Utility to convert [Valibot](https://valibot.dev) schemas to JSON Schema. Supports JSON Schema draft-07, draft-2020-12, and OpenAPI 3.0 Schema Object formats.
+
+```js
+import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+toJsonSchema(v.string()); // { $schema: "http://json-schema.org/draft-07/schema#", type: "string" }
+```
+
+This package is particularly popular for:
+
+- **API Documentation**: Generate OpenAPI specifications from your Valibot schemas
+- **Code Generation**: Create client SDKs and types from your validation schemas
+- **LLM Integration**: Generate structured outputs for Large Language Models
+- **Schema Sharing**: Share validation logic between different programming languages
+
+> Some Valibot features can't be mapped to JSON schema. For example, transformation actions have no equivalent in JSON schema. Also, some Valibot schemas or validations are too JS-specific and do not have an equivalent JSON schema attribute.
+
+## Supported features
+
+**Note**: Converted schemas may behave slightly differently in JSON schema validators (especially for string format) because their implementation is different from Valibot's.
+
+| Schema           | Status | Note                                                                                                                                  |
+| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `any`            | ✅     |                                                                                                                                       |
+| `array`          | ✅     |                                                                                                                                       |
+| `boolean`        | ✅     |                                                                                                                                       |
+| `enum`           | ⚠️     | Only JSON compatible values are supported                                                                                             |
+| `exactOptional`  | ✅     |                                                                                                                                       |
+| `intersect`      | ✅     |                                                                                                                                       |
+| `lazy`           | ⚠️     | The `.getter` function is always executed with `undefined` as input                                                                   |
+| `literal`        | ⚠️     | Only JSON compatible values are supported                                                                                             |
+| `looseObject`    | ✅     |                                                                                                                                       |
+| `looseTuple`     | ✅     |                                                                                                                                       |
+| `never`          | ✅     |                                                                                                                                       |
+| `null`           | ✅     |                                                                                                                                       |
+| `nullable`       | ✅     |                                                                                                                                       |
+| `nullish`        | ✅     |                                                                                                                                       |
+| `number`         | ✅     |                                                                                                                                       |
+| `objectWithRest` | ✅     |                                                                                                                                       |
+| `object`         | ✅     |                                                                                                                                       |
+| `optional`       | ✅     |                                                                                                                                       |
+| `picklist`       | ⚠️     | Only JSON compatible values are supported                                                                                             |
+| `record`         | ⚠️     | Only `string` schemas for the key of the record are supported. Adds `propertyNames` for key validation (not available in OpenAPI 3.0) |
+| `strictObject`   | ✅     |                                                                                                                                       |
+| `strictTuple`    | ✅     |                                                                                                                                       |
+| `string`         | ✅     |                                                                                                                                       |
+| `tupleWithRest`  | ✅     |                                                                                                                                       |
+| `tuple`          | ✅     |                                                                                                                                       |
+| `union`          | ✅     |                                                                                                                                       |
+| `undefinedable`  | ✅     |                                                                                                                                       |
+| `unknown`        | ✅     |                                                                                                                                       |
+| `variant`        | ⚠️     | The discriminator key will be ignored                                                                                                 |
+
+| Actions         | Status | Note                                                   |
+| --------------- | ------ | ------------------------------------------------------ |
+| `base64`        | ✅     |                                                        |
+| `bic`           | ✅     |                                                        |
+| `cuid2`         | ✅     |                                                        |
+| `decimal`       | ✅     |                                                        |
+| `description`   | ✅     |                                                        |
+| `digits`        | ✅     |                                                        |
+| `domain`        | ✅     |                                                        |
+| `email`         | ✅     |                                                        |
+| `emoji`         | ✅     |                                                        |
+| `empty`         | ✅     |                                                        |
+| `endsWith`      | ✅     |                                                        |
+| `entries`       | ✅     |                                                        |
+| `examples`      | ✅     |                                                        |
+| `gtValue`       | ⚠️     | Only in combination with `number` and `integer` schema |
+| `hash`          | ✅     |                                                        |
+| `hexadecimal`   | ✅     |                                                        |
+| `hexColor`      | ✅     |                                                        |
+| `includes`      | ✅     |                                                        |
+| `integer`       | ✅     |                                                        |
+| `ipv4`          | ✅     |                                                        |
+| `ipv6`          | ✅     |                                                        |
+| `isoDate`       | ✅     |                                                        |
+| `isoDateTime`   | ✅     |                                                        |
+| `isoTime`       | ✅     |                                                        |
+| `isoTimeSecond` | ✅     |                                                        |
+| `isoTimestamp`  | ✅     |                                                        |
+| `isoWeek`       | ✅     |                                                        |
+| `isrc`          | ✅     |                                                        |
+| `jwsCompact`    | ✅     |                                                        |
+| `ksuid`         | ✅     |                                                        |
+| `length`        | ⚠️     | Only in combination with `string` and `array` schema   |
+| `ltValue`       | ⚠️     | Only in combination with `number` and `integer` schema |
+| `mac`           | ✅     |                                                        |
+| `mac48`         | ✅     |                                                        |
+| `mac64`         | ✅     |                                                        |
+| `maxEntries`    | ✅     |                                                        |
+| `maxLength`     | ⚠️     | Only in combination with `string` and `array` schema   |
+| `maxValue`      | ⚠️     | Only in combination with `number` schema               |
+| `metadata`      | ✅     | Additional properties are added without validation     |
+| `minEntries`    | ✅     |                                                        |
+| `minLength`     | ⚠️     | Only in combination with `string` and `array` schema   |
+| `minValue`      | ⚠️     | Only in combination with `number` schema               |
+| `multipleOf`    | ✅     |                                                        |
+| `nanoid`        | ✅     |                                                        |
+| `nonEmpty`      | ✅     |                                                        |
+| `notValue`      | ⚠️     | Only JSON compatible values are supported              |
+| `notValues`     | ⚠️     | Only JSON compatible values are supported              |
+| `octal`         | ✅     |                                                        |
+| `regex`         | ⚠️     | RegExp flags are not supported in JSON Schema          |
+| `rfcEmail`      | ✅     |                                                        |
+| `safeInteger`   | ✅     |                                                        |
+| `slug`          | ✅     |                                                        |
+| `startsWith`    | ✅     |                                                        |
+| `title`         | ✅     |                                                        |
+| `ulid`          | ✅     |                                                        |
+| `url`           | ✅     |                                                        |
+| `uuid`          | ✅     |                                                        |
+| `value`         | ⚠️     | Only JSON compatible values are supported              |
+| `values`        | ⚠️     | Only JSON compatible values are supported              |
+
+> For `length`, `minLength`, and `maxLength`, string constraints have different length semantics in Valibot and JSON Schema. Valibot checks JavaScript string length (`value.length`, UTF-16 code units), while JSON Schema `minLength` and `maxLength` count Unicode code points. This can differ for non-BMP code points such as emoji and for multi-code-point grapheme clusters such as combining marks or ZWJ sequences.
+
+## Configurations
+
+| Option         | Type                                                                  | Note                                                                                                                      |
+| -------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| target         | `'draft-07' \| 'draft-2020-12' \| 'openapi-3.0'`                      | The target JSON Schema format. Defaults to `'draft-07'`.                                                                  |
+| typeMode       | `'ignore' \| 'input' \| 'output'`                                     | Whether to convert the input or output type of the Valibot schema to JSON Schema.                                         |
+| errorMode      | `'throw' \| 'warn' \| 'ignore'`                                       | The policy for handling incompatible schemas and actions.                                                                 |
+| definitions    | `Record<string, GenericSchema>`                                       | The schema definitions for constructing recursive schemas. If not specified, the definitions are generated automatically. |
+| overrideSchema | `(context: OverrideSchemaContext) => JsonSchema \| null \| undefined` | Overrides the JSON Schema conversion for a specific Valibot schema.                                                       |
+| ignoreActions  | `string[]`                                                            | The actions that should be ignored during the conversion.                                                                 |
+| overrideAction | `(context: OverrideActionContext) => JsonSchema \| null \| undefined` | Overrides the JSON Schema reference for a specific Valibot action.                                                        |
+| overrideRef    | `(context: OverrideRefContext) => string \| null \| undefined`        | Overrides the JSON Schema reference for a specific reference ID.                                                          |
+
+### Target format
+
+The `target` configuration allows you to specify which JSON Schema format to generate. Different targets have different capabilities and syntax:
+
+```js
+import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const schema = v.nullable(v.string());
+
+// JSON Schema draft-07 (default)
+toJsonSchema(schema);
+// { $schema: "http://json-schema.org/draft-07/schema#", anyOf: [{ type: "string" }, { type: "null" }] }
+
+// JSON Schema draft-2020-12
+toJsonSchema(schema, { target: 'draft-2020-12' });
+// { $schema: "https://json-schema.org/draft/2020-12/schema", anyOf: [{ type: "string" }, { type: "null" }] }
+
+// OpenAPI 3.0 Schema Object
+toJsonSchema(schema, { target: 'openapi-3.0' });
+// { type: "string", nullable: true }
+```
+
+**Note**: Some features like `propertyNames` for record schemas are not available in OpenAPI 3.0.
+
+### Type mode
+
+The `typeMode` configuration controls whether to convert the input or output type of the Valibot schema to JSON Schema.
+
+- When set to `'input'`, conversion stops before the first potential type transformation action or second schema in any pipeline.
+- When set to `'output'`, conversion of any pipelines starts from the last schema in the pipeline. Therefore, the output type must be specified explicitly with a schema after the last type transformation action.
+- When set to `'ignore'` (default), the entire pipeline is converted.
+
+This is particularly useful when defining API endpoints where external developers need different schema information for requests vs responses:
+
+```js
+import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const ValibotSchema = v.pipe(
+  v.string(),
+  v.decimal(),
+  v.transform(Number),
+  v.number(),
+  v.maxValue(100)
+);
+
+toJsonSchema(ValibotSchema, { typeMode: 'input' });
+
+// {
+//   $schema: "http://json-schema.org/draft-07/schema#",
+//   type: "string",
+//   pattern: "^[+-]?(?:\\d*\\.)?\\d+$"
+// }
+
+toJsonSchema(ValibotSchema, { typeMode: 'output' });
+
+// {
+//   $schema: "http://json-schema.org/draft-07/schema#",
+//   type: "number",
+//   maximum: 100
+// }
+```
+
+### Error mode
+
+The `errorMode` configuration controls how the converter handles unsupported schemas and actions. By default, the error mode is set to `'throw'`. To force the conversion of unsupported Valibot features, you can set it to `'ignore'`.
+
+> Unsupported schemas usually return an empty JSON schema (`{}`) and unsupported actions are usually ignored.
+
+```js
+import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+toJsonSchema(v.file(), { errorMode: 'ignore' }); // {}
+
+toJsonSchema(v.pipe(v.string(), v.creditCard()), { errorMode: 'ignore' }); // { type: "string" }
+```
+
+### Override functions
+
+The package provides powerful override capabilities to customize the JSON Schema conversion process. You can override the conversion of specific schemas, actions, or references.
+
+#### Override schema conversion
+
+Handle unsupported schemas or customize conversion behavior:
+
+```js
+import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const ValibotSchema = v.object({ createdAt: v.date() });
+
+toJsonSchema(ValibotSchema, {
+  overrideSchema(context) {
+    if (context.valibotSchema.type === 'date') {
+      return { type: 'string', format: 'date-time' };
+    }
+  },
+});
+
+// {
+//   $schema: "http://json-schema.org/draft-07/schema#",
+//   type: "object",
+//   properties: {
+//     createdAt: { type: "string" format: "date-time" }
+//   },
+//   required: ["createdAt"]
+// }
+```
+
+#### Override reference IDs
+
+Customize reference IDs for OpenAPI or other specifications:
+
+```js
+import { toJsonSchemaDefs } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const UserSchema = v.object({ name: v.string() });
+
+toJsonSchemaDefs(
+  { UserSchema },
+  { overrideRef: (context) => `#/schemas/${context.referenceId}` }
+);
+```
+
+### Enhanced metadata support
+
+Use the generic `metadata` action to add title, description, and examples to your schemas or the individual `title` and `description` actions. Any other properties of the `metadata` action are added to the JSON Schema without further validation. This allows you to specify custom annotations and standard keywords such as `format`:
+
+```js
+import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const ValibotSchema = v.pipe(
+  v.string(),
+  v.email(),
+  v.metadata({
+    title: 'Email Schema',
+    description: 'A schema that validates email addresses.',
+    examples: ['jane@example.com'],
+    'x-category': 'auth',
+  })
+);
+
+toJsonSchema(ValibotSchema);
+
+// {
+//   $schema: "http://json-schema.org/draft-07/schema#",
+//   type: "string",
+//   format: "email",
+//   title: "Email Schema",
+//   description: "A schema that validates email addresses.",
+//   examples: ["jane@example.com"],
+//   "x-category": "auth"
+// }
+```
+
+### Definitions
+
+Nested and recursive schemas can be broken in multiple reusable definitions.
+
+```js
+import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const EmailSchema = v.pipe(v.string(), v.email());
+toJsonSchema(v.object({ email: EmailSchema }), {
+  definitions: { EmailSchema },
+});
+
+// {
+//   $schema: "http://json-schema.org/draft-07/schema#",
+//   type: "object",
+//   properties: {
+//     email: {
+//       $ref: "#/$defs/EmailSchema"
+//     }
+//   },
+//   required: ["email"],
+//   $defs: {
+//     EmailSchema: {
+//       type: "string",
+//       format: "email"
+//     }
+//   }
+// }
+```
+
+Definitions are not required for converting `lazy` schemas. Missing definitions will be generated automatically.
+
+```js
+import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const StringSchema = v.string();
+toJsonSchema(v.object({ key: v.lazy(() => StringSchema) }));
+
+// {
+//   $schema: "http://json-schema.org/draft-07/schema#",
+//   type: "object",
+//   properties: {
+//     key: {
+//       $ref: "#/$defs/0"
+//     }
+//   },
+//   required: ["key"],
+//   $defs: {
+//     0: {
+//       type: "string"
+//     }
+//   }
+// }
+```
+
+## Additional functions
+
+### `toStandardJsonSchema`
+
+Converts a Valibot schema to the [Standard JSON Schema](https://standardschema.dev/) format. This format is useful when working with tools and libraries that support the Standard JSON Schema specification.
+
+```js
+import { toStandardJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const schema = toStandardJsonSchema(
+  v.object({
+    id: v.pipe(v.string(), v.uuid()),
+    name: v.pipe(v.string(), v.nonEmpty()),
+    age: v.optional(v.number()),
+  })
+);
+```
+
+### `toJsonSchemaDefs`
+
+Converts only the provided Valibot schema definitions to JSON Schema definitions, without wrapping them in a root schema. This is particularly useful for OpenAPI specifications where you need only the schema definitions.
+
+```js
+import { toJsonSchemaDefs } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const EmailSchema = v.pipe(v.string(), v.email());
+const UserSchema = v.object({
+  name: v.string(),
+  email: EmailSchema,
+});
+
+toJsonSchemaDefs({ EmailSchema, UserSchema });
+
+// {
+//   EmailSchema: {
+//     type: "string",
+//     format: "email"
+//   },
+//   UserSchema: {
+//     type: "object",
+//     properties: {
+//       name: {
+//         type: "string"
+//       },
+//       email: {
+//         $ref: "#/$defs/EmailSchema"
+//       }
+//     },
+//     required: ["name", "email"]
+//   }
+// }
+```
+
+#### OpenAPI integration
+
+For OpenAPI specifications, you can customize reference IDs:
+
+```js
+import { toJsonSchemaDefs } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const ValibotSchema1 = v.string();
+const ValibotSchema2 = v.number();
+const ValibotSchema3 = v.tuple([ValibotSchema1, ValibotSchema2]);
+
+toJsonSchemaDefs(
+  { ValibotSchema1, ValibotSchema2, ValibotSchema3 },
+  { overrideRef: (context) => `#/schemas/${context.referenceId}` }
+);
+
+// {
+//   ValibotSchema1: { type: "string" },
+//   ValibotSchema2: { type: "number" },
+//   ValibotSchema3: {
+//     type: "array",
+//     items: [
+//       { $ref: "#/schemas/ValibotSchema1" },
+//       { $ref: "#/schemas/ValibotSchema2" }
+//     ],
+//     minItems: 2
+//   }
+// }
+```
+
+### Global definitions
+
+For advanced use cases, you can manage global schema definitions that will be automatically used when converting schemas. This is particularly useful for larger projects with many reusable schemas.
+
+```js
+import { addGlobalDefs, toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const ValibotSchema1 = v.string();
+const ValibotSchema2 = v.number();
+
+addGlobalDefs({ ValibotSchema1, ValibotSchema2 });
+
+const ValibotSchema3 = v.tuple([ValibotSchema1, ValibotSchema2]);
+
+toJsonSchema(ValibotSchema3);
+
+// {
+//   $schema: "http://json-schema.org/draft-07/schema#",
+//   type: "array",
+//   items: [
+//     { $ref: "#/$defs/ValibotSchema1" },
+//     { $ref: "#/$defs/ValibotSchema2" }
+//   ],
+//   minItems: 2,
+//   $defs: {
+//     ValibotSchema1: { type: "string" },
+//     ValibotSchema2: { type: "number" }
+//   }
+// }
+```
+
+You can also convert global definitions directly using `toJsonSchemaDefs`:
+
+```js
+const globalDefs = getGlobalDefs();
+if (globalDefs) {
+  const schemaDefs = toJsonSchemaDefs(globalDefs);
+}
+```