toolcraft-schema 0.0.42 → 0.0.43

package/dist/index.d.ts

@@ -16,6 +16,7 @@ type JsonSchemaEnumValue = EnumValue | null;
 type NumberJsonType = "number" | "integer";
 type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
 type ObjectShape = Record<string, AnySchema>;
+type EmptyOptions = Record<never, never>;
 type SchemaScope = "cli" | "mcp" | "sdk";
 type StringMetadata = {
     format?: string;
@@ -56,6 +57,13 @@ type SchemaOptions<TDefault> = {
     scope?: readonly SchemaScope[];
     global?: boolean;
 };
+type WithNullable<TSchema extends AnySchema, TOptions extends {
+    nullable?: boolean;
+}> = TOptions extends {
+    readonly nullable: true;
+} ? TSchema & {
+    readonly nullable: true;
+} : TSchema;
 export interface SchemaBase<TKind extends SchemaKind, TStatic> {
     readonly kind: TKind;
     readonly description?: string;
@@ -116,14 +124,16 @@ export interface OptionalSchema<TInner extends AnySchema> extends SchemaBase<"op
     readonly inner: TInner;
 }
 export type AnySchema = StringSchema | NumberSchema | BooleanSchema | EnumSchema<NonEmptyReadonlyArray<EnumValue>> | ArraySchema<AnySchema> | ObjectSchema<ObjectShape> | OptionalSchema<AnySchema> | OneOfSchema<Record<string, ObjectSchema<any>>, string> | UnionSchema<readonly ObjectSchema<any>[]> | RecordSchema<AnySchema> | JsonValueSchema;
-export type Static<TSchema extends AnySchema> = TSchema extends SchemaBase<any, infer TStatic> ? TStatic : never;
+export type Static<TSchema extends AnySchema> = TSchema extends {
+    readonly nullable: true;
+} ? TSchema extends SchemaBase<any, infer TStatic> ? TStatic | null : never : TSchema extends SchemaBase<any, infer TStatic> ? TStatic : never;
 export declare const S: {
-    readonly String: (options?: SchemaOptions<string> & StringMetadata) => StringSchema;
-    readonly Number: (options?: SchemaOptions<number> & NumberMetadata & {
+    readonly String: <const TOptions extends SchemaOptions<string> & StringMetadata = EmptyOptions>(options?: TOptions) => WithNullable<StringSchema, TOptions>;
+    readonly Number: <const TOptions extends SchemaOptions<number> & NumberMetadata & {
         jsonType?: NumberJsonType;
-    }) => NumberSchema;
-    readonly Boolean: (options?: SchemaOptions<boolean>) => BooleanSchema;
-    readonly Enum: <const TValues extends NonEmptyReadonlyArray<EnumValue>>(values: TValues, options?: SchemaOptions<TValues[number]> & {
+    } = EmptyOptions>(options?: TOptions) => WithNullable<NumberSchema, TOptions>;
+    readonly Boolean: <const TOptions extends SchemaOptions<boolean> = EmptyOptions>(options?: TOptions) => WithNullable<BooleanSchema, TOptions>;
+    readonly Enum: <const TValues extends NonEmptyReadonlyArray<EnumValue>, const TOptions extends SchemaOptions<TValues[number]> & {
         jsonType?: "integer";
         labels?: Partial<Record<string, string>>;
         loadOptions?: (() => Array<{
@@ -133,9 +143,9 @@ export declare const S: {
             label: string;
             value: string;
         }>>);
-    }) => EnumSchema<TValues>;
-    readonly Array: <TItem extends AnySchema>(item: TItem, options?: SchemaOptions<Array<Static<TItem>>> & ArrayMetadata) => ArraySchema<TItem>;
-    readonly Object: <const TShape extends ObjectShape>(shape: TShape, options?: SchemaOptions<InferObject<TShape>> & ObjectMetadata) => ObjectSchema<TShape>;
+    } = EmptyOptions>(values: TValues, options?: TOptions) => WithNullable<EnumSchema<TValues>, TOptions>;
+    readonly Array: <TItem extends AnySchema, const TOptions extends SchemaOptions<Array<Static<TItem>>> & ArrayMetadata = EmptyOptions>(item: TItem, options?: TOptions) => WithNullable<ArraySchema<TItem>, TOptions>;
+    readonly Object: <const TShape extends ObjectShape, const TOptions extends SchemaOptions<InferObject<TShape>> & ObjectMetadata = EmptyOptions>(shape: TShape, options?: TOptions) => WithNullable<ObjectSchema<TShape>, TOptions>;
     readonly Optional: <TInner extends AnySchema>(inner: TInner) => OptionalSchema<TInner>;
     readonly OneOf: typeof OneOf;
     readonly Union: typeof Union;

package/dist/index.js

@@ -50,9 +50,7 @@ function withArrayMetadata(schema, jsonSchema) {
     return withMetadata(schema, jsonSchema);
 }
 function withObjectMetadata(schema, jsonSchema) {
-    if (schema.additionalProperties !== undefined) {
-        jsonSchema.additionalProperties = schema.additionalProperties;
-    }
+    jsonSchema.additionalProperties = schema.additionalProperties ?? false;
     return withMetadata(schema, jsonSchema);
 }
 function getEnumJsonType(values) {
@@ -95,6 +93,20 @@ function assertFiniteNumber(value, name) {
         throw new Error(`${name} must be finite`);
     }
 }
+function assertMinMaxOrder(minimum, maximum, minimumName, maximumName) {
+    if (minimum !== undefined && maximum !== undefined && minimum > maximum) {
+        throw new Error(`${minimumName} must be less than or equal to ${maximumName}`);
+    }
+}
+function assertValidDefault(schema) {
+    if (schema.default === undefined) {
+        return;
+    }
+    const result = validate(schema, schema.default);
+    if (!result.ok) {
+        throw new Error(`default must satisfy schema: ${result.issues[0]?.message ?? "invalid default"}`);
+    }
+}
 function assertPattern(pattern) {
     if (pattern === undefined) {
         return;
@@ -133,31 +145,39 @@ export const S = {
     String(options = {}) {
         assertNonNegativeInteger(options.minLength, "minLength");
         assertNonNegativeInteger(options.maxLength, "maxLength");
+        assertMinMaxOrder(options.minLength, options.maxLength, "minLength", "maxLength");
         assertPattern(options.pattern);
-        return {
+        const schema = {
             kind: "string",
             ...options
         };
+        assertValidDefault(schema);
+        return schema;
     },
     Number(options = {}) {
         assertFiniteNumber(options.minimum, "minimum");
         assertFiniteNumber(options.maximum, "maximum");
+        assertMinMaxOrder(options.minimum, options.maximum, "minimum", "maximum");
         assertFiniteNumber(options.default, "default");
         if (options.jsonType === "integer" &&
             options.default !== undefined &&
             !Number.isInteger(options.default)) {
             throw new Error("default must be an integer");
         }
-        return {
+        const schema = {
             kind: "number",
             ...options
         };
+        assertValidDefault(schema);
+        return schema;
     },
     Boolean(options = {}) {
-        return {
+        const schema = {
             kind: "boolean",
             ...options
         };
+        assertValidDefault(schema);
+        return schema;
     },
     Enum(values, options = {}) {
         assertValidEnumValues(values);
@@ -165,27 +185,34 @@ export const S = {
             values.some((value) => typeof value !== "number" || !Number.isInteger(value))) {
             throw new Error("Integer enum values must be integers");
         }
-        return {
+        const schema = {
             kind: "enum",
             values,
             ...options
         };
+        assertValidDefault(schema);
+        return schema;
     },
     Array(item, options = {}) {
         assertNonNegativeInteger(options.minItems, "minItems");
         assertNonNegativeInteger(options.maxItems, "maxItems");
-        return {
+        assertMinMaxOrder(options.minItems, options.maxItems, "minItems", "maxItems");
+        const schema = {
             kind: "array",
             item,
             ...options
         };
+        assertValidDefault(schema);
+        return schema;
     },
     Object(shape, options = {}) {
-        return {
+        const schema = {
             kind: "object",
             shape,
             ...options
         };
+        assertValidDefault(schema);
+        return schema;
     },
     Optional(inner) {
         return {

package/package.json

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