toolcraft-schema 0.0.38 → 0.0.40

package/README.md

@@ -10,18 +10,19 @@ Zero-dependency schema builder for typed command inputs and JSON Schema generati
 - Typed schema descriptors
 - `Static<typeof schema>` type inference
 - JSON Schema serialization via `toJsonSchema()`
+- JSON Schema document serialization via `toJsonSchemaDocument()`
 
 ## Usage
 
 ```ts
-import { S, toJsonSchema } from "toolcraft-schema";
+import { S, toJsonSchema, toJsonSchemaDocument } from "toolcraft-schema";
 import type { Static } from "toolcraft-schema";
 
 const schema = S.Object({
   name: S.String({ description: "User name" }),
   retries: S.Optional(S.Number({ default: 3 })),
   mode: S.Enum(["fast", "safe"] as const, { default: "safe" }),
-  tags: S.Array(S.String(), { default: [] }),
+  tags: S.Array(S.String(), { default: [] })
 });
 
 type Input = Static<typeof schema>;
@@ -33,17 +34,21 @@ type Input = Static<typeof schema>;
 // }
 
 const jsonSchema = toJsonSchema(schema);
+const document = toJsonSchemaDocument(schema, {
+  id: "https://example.test/schema.json",
+  title: "Example schema"
+});
 ```
 
 ## API
 
 ### Builders
 
-- `S.String({ description?, default? })`
-- `S.Number({ description?, default? })`
-- `S.Boolean({ description?, default? })`
-- `S.Enum(values, { description?, default? })`
-- `S.Array(itemSchema, { description?, default? })`
+- `S.String({ description?, default?, short?, cliAliases? })`
+- `S.Number({ description?, default?, short?, cliAliases? })`
+- `S.Boolean({ description?, default?, short?, cliAliases? })`
+- `S.Enum(values, { description?, default?, short?, cliAliases? })`
+- `S.Array(itemSchema, { description?, default?, short?, cliAliases? })`
 - `S.Object({ [key]: schema })`
 - `S.Optional(schema)`
 
@@ -55,6 +60,7 @@ const jsonSchema = toJsonSchema(schema);
 ### JSON Schema generation
 
 - `toJsonSchema(schema)` converts any schema descriptor to standard JSON Schema.
+- `toJsonSchemaDocument(schema, options)` wraps `toJsonSchema(schema)` in a full JSON Schema document with `$schema`, optional `$id`, `title`, and `description`.
 - Object properties not wrapped in `S.Optional(...)` are emitted in `required`.
 - Defaults provided to schema builders are emitted as JSON Schema `default`.
 - Nested `S.Object(...)` schemas produce nested JSON Schema objects.

package/dist/index.compile-check.js

@@ -1,4 +1,4 @@
-import { S } from "./index.js";
+import { S, toJsonSchemaDocument } from "./index.js";
 const ignoredStringSchema = S.String({ description: "Name", default: "guest" });
 const ignoredNumberSchema = S.Number({ description: "Count", default: 1 });
 const ignoredBooleanSchema = S.Boolean({ description: "Enabled", default: false });
@@ -7,6 +7,11 @@ const ignoredIntegerEnumSchema = S.Enum([1, 2], { jsonType: "integer" });
 const ignoredArraySchema = S.Array(S.String(), { default: ["a"] });
 const ignoredObjectSchema = S.Object({
     name: S.String(),
-    retries: S.Optional(S.Number()),
+    retries: S.Optional(S.Number())
 });
 const ignoredOptionalSchema = S.Optional(S.Boolean());
+const ignoredJsonSchemaDocument = toJsonSchemaDocument(ignoredObjectSchema, {
+    id: "https://example.test/schema.json",
+    title: "Example schema",
+    description: "Example schema document"
+});

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { Record as RecordBuilder } from "./record.js";
 import { Union } from "./union.js";
 import { validate } from "./validate.js";
 import type { JsonValue, JsonValueSchema } from "./json.js";
+import type { JsonSchemaDocument, JsonSchemaDocumentOptions } from "./json-schema-document.js";
 import type { OneOfSchema } from "./oneof.js";
 import type { RecordSchema } from "./record.js";
 import type { UnionSchema } from "./union.js";
@@ -47,6 +48,7 @@ type InferObject<TShape extends ObjectShape> = {
 };
 type SchemaOptions<TDefault> = {
     description?: string;
+    cliAliases?: readonly string[];
     default?: TDefault;
     nullable?: boolean;
     requiredScopes?: readonly SchemaScope[];
@@ -57,6 +59,7 @@ type SchemaOptions<TDefault> = {
 export interface SchemaBase<TKind extends SchemaKind, TStatic> {
     readonly kind: TKind;
     readonly description?: string;
+    readonly cliAliases?: readonly string[];
     readonly default?: TStatic;
     readonly nullable?: boolean;
     readonly requiredScopes?: readonly SchemaScope[];
@@ -140,5 +143,7 @@ export declare const S: {
     readonly Json: typeof Json;
 };
 export declare function toJsonSchema(schema: AnySchema): JsonSchema;
+export declare function toJsonSchemaDocument(schema: AnySchema, options?: JsonSchemaDocumentOptions): JsonSchemaDocument;
 export { Json, OneOf, RecordBuilder as Record, Union, validate };
-export type { JsonValue, JsonValueSchema, OneOfSchema, RecordSchema, UnionSchema, ValidationIssue, ValidationResult, };
+export type { JsonSchemaDocument, JsonSchemaDocumentOptions } from "./json-schema-document.js";
+export type { JsonValue, JsonValueSchema, OneOfSchema, RecordSchema, UnionSchema, ValidationIssue, ValidationResult };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { Json } from "./json.js";
+import { createJsonSchemaDocument } from "./json-schema-document.js";
 import { OneOf } from "./oneof.js";
 import { Record as RecordBuilder } from "./record.js";
 import { Union } from "./union.js";
@@ -117,15 +118,15 @@ function withInjectedDiscriminator(schema, discriminator, branchName) {
         ...(branchJsonSchema.properties ?? {}),
         [discriminator]: {
             type: "string",
-            enum: [branchName],
-        },
+            enum: [branchName]
+        }
     };
     const required = [...new Set([...(branchJsonSchema.required ?? []), discriminator])];
     return {
         ...branchJsonSchema,
         type: "object",
         properties,
-        required,
+        required
     };
 }
 export const S = {
@@ -135,36 +136,39 @@ export const S = {
         assertPattern(options.pattern);
         return {
             kind: "string",
-            ...options,
+            ...options
         };
     },
     Number(options = {}) {
         assertFiniteNumber(options.minimum, "minimum");
         assertFiniteNumber(options.maximum, "maximum");
         assertFiniteNumber(options.default, "default");
-        if (options.jsonType === "integer" && options.default !== undefined && !Number.isInteger(options.default)) {
+        if (options.jsonType === "integer" &&
+            options.default !== undefined &&
+            !Number.isInteger(options.default)) {
             throw new Error("default must be an integer");
         }
         return {
             kind: "number",
-            ...options,
+            ...options
         };
     },
     Boolean(options = {}) {
         return {
             kind: "boolean",
-            ...options,
+            ...options
         };
     },
     Enum(values, options = {}) {
         assertValidEnumValues(values);
-        if (options.jsonType === "integer" && values.some((value) => typeof value !== "number" || !Number.isInteger(value))) {
+        if (options.jsonType === "integer" &&
+            values.some((value) => typeof value !== "number" || !Number.isInteger(value))) {
             throw new Error("Integer enum values must be integers");
         }
         return {
             kind: "enum",
             values,
-            ...options,
+            ...options
         };
     },
     Array(item, options = {}) {
@@ -173,26 +177,26 @@ export const S = {
         return {
             kind: "array",
             item,
-            ...options,
+            ...options
         };
     },
     Object(shape, options = {}) {
         return {
             kind: "object",
             shape,
-            ...options,
+            ...options
         };
     },
     Optional(inner) {
         return {
             kind: "optional",
-            inner,
+            inner
         };
     },
     OneOf,
     Union,
     Record: RecordBuilder,
-    Json,
+    Json
 };
 export function toJsonSchema(schema) {
     const unwrappedSchema = unwrapOptional(schema);
@@ -207,7 +211,7 @@ export function toJsonSchema(schema) {
             const jsonSchema = {
                 enum: unwrappedSchema.nullable === true
                     ? [...unwrappedSchema.values, null]
-                    : [...unwrappedSchema.values],
+                    : [...unwrappedSchema.values]
             };
             const enumType = unwrappedSchema.jsonType ?? getEnumJsonType(unwrappedSchema.values);
             if (enumType !== undefined) {
@@ -218,7 +222,7 @@ export function toJsonSchema(schema) {
         case "array":
             return withArrayMetadata(unwrappedSchema, {
                 type: "array",
-                items: toJsonSchema(unwrappedSchema.item),
+                items: toJsonSchema(unwrappedSchema.item)
             });
         case "object": {
             const properties = {};
@@ -237,24 +241,27 @@ export function toJsonSchema(schema) {
             return withObjectMetadata(unwrappedSchema, {
                 type: "object",
                 properties,
-                required,
+                required
             });
         }
         case "oneOf":
             return withMetadata(unwrappedSchema, {
-                oneOf: Object.entries(unwrappedSchema.branches).map(([branchName, branchSchema]) => withInjectedDiscriminator(branchSchema, unwrappedSchema.discriminator, branchName)),
+                oneOf: Object.entries(unwrappedSchema.branches).map(([branchName, branchSchema]) => withInjectedDiscriminator(branchSchema, unwrappedSchema.discriminator, branchName))
             });
         case "union":
             return withMetadata(unwrappedSchema, {
-                oneOf: unwrappedSchema.branches.map((branchSchema) => toJsonSchema(branchSchema)),
+                oneOf: unwrappedSchema.branches.map((branchSchema) => toJsonSchema(branchSchema))
             });
         case "record":
             return withMetadata(unwrappedSchema, {
                 type: "object",
-                additionalProperties: toJsonSchema(unwrappedSchema.value),
+                additionalProperties: toJsonSchema(unwrappedSchema.value)
             });
         case "json":
             return withMetadata(unwrappedSchema, {});
     }
 }
+export function toJsonSchemaDocument(schema, options = {}) {
+    return createJsonSchemaDocument(toJsonSchema(schema), options);
+}
 export { Json, OneOf, RecordBuilder as Record, Union, validate };

package/dist/json-schema-document.d.ts

@@ -0,0 +1,14 @@
+import type { JsonSchema } from "./index.js";
+export interface JsonSchemaDocumentOptions {
+    id?: string;
+    title?: string;
+    description?: string;
+    schema?: string;
+}
+export type JsonSchemaDocument = JsonSchema & {
+    $schema: string;
+    $id?: string;
+    title?: string;
+    description?: string;
+};
+export declare function createJsonSchemaDocument(jsonSchema: JsonSchema, options?: JsonSchemaDocumentOptions): JsonSchemaDocument;

package/dist/json-schema-document.js

@@ -0,0 +1,17 @@
+export function createJsonSchemaDocument(jsonSchema, options = {}) {
+    const { id, schema: schemaUri = "https://json-schema.org/draft/2020-12/schema", ...metadata } = options;
+    const document = {
+        $schema: schemaUri,
+        ...jsonSchema
+    };
+    if (id !== undefined) {
+        document.$id = id;
+    }
+    if (metadata.title !== undefined) {
+        document.title = metadata.title;
+    }
+    if (metadata.description !== undefined) {
+        document.description = metadata.description;
+    }
+    return document;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",