runcheck 1.11.0 → 1.13.0

package/dist/runcheck.d.ts

@@ -1,8 +1,19 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
- * If the schema key value is undefined uses a value from the fallback key as a safe value
- * Can be used to rename keys from input
+ * Creates a type that uses a fallback key when the primary key is undefined.
+ * Can be used to rename keys from input or provide alternative key names.
+ * @param fallbackKey - The alternative key to use when the primary key is undefined
+ * @param type - The type to validate the value against
+ * @returns A runcheck type that supports fallback key lookup
+ * @example
+ * ```typescript
+ * const userSchema = rc_object({
+ *   name: rc_get_from_key_as_fallback('username', rc_string)
+ * })
+ * // Will look for 'name' first, then 'username' if 'name' is undefined
+ * const result = userSchema.parse({ username: 'john' }) // valid
+ * ```
  */
 declare function rc_get_from_key_as_fallback<T extends RcType<any>>(fallbackKey: string, type: T): RcType<RcInferType<T>>;
 type RcObject = {
@@ -25,23 +36,137 @@ type Flatten<T> = Identity<{
 }>;
 type ObjOptions = {
     normalizeKeysFrom?: 'snake_case';
+    /** excess keys are not removed if extends is true */
+    extends?: boolean;
 };
-declare function rc_object<T extends RcObject>(shape: T, { normalizeKeysFrom }?: ObjOptions): RcObjTypeReturn<T>;
-declare function rc_obj_extends<T extends RcObject>(shape: T, options?: ObjOptions): RcObjTypeReturn<T>;
+/**
+ * Creates an object type validator with specified shape and options.
+ * @param shape - The object shape defining the expected properties and their types
+ * @param options - Configuration options for the object validator
+ * @param options.normalizeKeysFrom - If 'snake_case', automatically converts camelCase keys to snake_case for lookup
+ * @param options.extends - If true, allows excess properties in the input object
+ * @returns A runcheck type that validates objects with the specified shape
+ * @example
+ * ```typescript
+ * const userSchema = rc_object({
+ *   name: rc_string,
+ *   age: rc_number,
+ *   email: rc_string.optional()
+ * })
+ * const result = userSchema.parse({ name: 'John', age: 30 }) // valid
+ * ```
+ */
+declare function rc_object<T extends RcObject>(shape: T, { normalizeKeysFrom, extends: extendsObj }?: ObjOptions): RcObjTypeReturn<T>;
+type ExtendsOptions = Omit<ObjOptions, 'extends'>;
+/**
+ * Creates an object type that extends the input with additional properties.
+ * Unlike strict objects, this allows excess properties from the input to be preserved.
+ * @param shapeOrSchema - Either an object shape or an existing object type
+ * @param options - Configuration options (excluding 'extends' which is always true)
+ * @returns A runcheck type that validates and extends objects
+ * @example
+ * ```typescript
+ * const baseSchema = rc_obj_extends({
+ *   name: rc_string
+ * })
+ * // Input: { name: 'John', extra: 'data' }
+ * // Output: { name: 'John', extra: 'data' } (preserves extra properties)
+ * ```
+ */
+declare function rc_obj_extends<T extends RcObject>(shape: T, options?: ExtendsOptions): RcObjTypeReturn<T>;
+declare function rc_obj_extends<T extends Record<string, any>>(schema: RcType<T>, options?: ExtendsOptions): RcType<T>;
+/**
+ * Extracts the object shape from an object type for inspection or manipulation.
+ * @param type - The object type to extract the shape from
+ * @returns The object shape containing the property types
+ * @throws Error if the type is not an object type
+ * @example
+ * ```typescript
+ * const userSchema = rc_object({ name: rc_string, age: rc_number })
+ * const shape = rc_get_obj_shape(userSchema)
+ * // shape = { name: RcType<string>, age: RcType<number> }
+ * ```
+ */
 declare function rc_get_obj_shape<T extends Record<string, any>>(type: RcType<T>): {
     [K in keyof T]: RcType<T[K]>;
 };
-/** return an error if the obj has more keys than the expected type */
+/**
+ * Creates a strict object type that rejects input with excess properties.
+ * @param shape - The object shape defining the expected properties and their types
+ * @param options - Configuration options for the object validator
+ * @returns A runcheck type that validates objects strictly (no excess properties allowed)
+ * @example
+ * ```typescript
+ * const strictUser = rc_obj_strict({
+ *   name: rc_string,
+ *   age: rc_number
+ * })
+ * const result = strictUser.parse({ name: 'John', age: 30 }) // valid
+ * const result2 = strictUser.parse({ name: 'John', age: 30, extra: 'data' }) // invalid
+ * ```
+ */
 declare function rc_obj_strict<T extends RcObject>(shape: T, options?: ObjOptions): RcObjTypeReturn<T>;
+/**
+ * Enables strict object validation for a type, rejecting excess properties.
+ * @param type - The type to make strict
+ * @param options - Configuration options
+ * @param options.nonRecursive - If true, only affects the immediate object type, not nested objects
+ * @returns The type with strict object validation enabled
+ * @example
+ * ```typescript
+ * const userSchema = rc_object({ name: rc_string, age: rc_number })
+ * const strictUser = rc_enable_obj_strict(userSchema)
+ * // Now rejects objects with excess properties
+ * ```
+ */
 declare function rc_enable_obj_strict<T extends RcType<any>>(type: T, { nonRecursive, }?: {
     nonRecursive?: boolean;
 }): T;
 type AnyObj = Record<string, unknown>;
 type Extends<T extends AnyObj, W extends AnyObj> = Omit<T, keyof W> & W;
+/**
+ * Merges multiple object types into a single object type.
+ * Later objects override properties from earlier objects.
+ * @param objs - The object types to merge (2-4 objects supported)
+ * @returns A runcheck type representing the merged object
+ * @example
+ * ```typescript
+ * const base = rc_object({ name: rc_string, age: rc_number })
+ * const extended = rc_object({ email: rc_string, age: rc_string }) // age overrides
+ * const merged = rc_obj_merge(base, extended)
+ * // Result: { name: string, age: string, email: string }
+ * ```
+ */
 declare function rc_obj_merge<A extends AnyObj, B extends AnyObj>(...objs: [RcType<A>, RcType<B>]): RcType<Extends<A, B>>;
 declare function rc_obj_merge<A extends AnyObj, B extends AnyObj, C extends AnyObj>(...objs: [RcType<A>, RcType<B>, RcType<C>]): RcType<Extends<Extends<A, B>, C>>;
 declare function rc_obj_merge<A extends AnyObj, B extends AnyObj, C extends AnyObj, D extends AnyObj>(...objs: [RcType<A>, RcType<B>, RcType<C>, RcType<D>]): RcType<Extends<Extends<Extends<A, B>, C>, D>>;
+/**
+ * Creates a new object type with only the specified properties from the original.
+ * @param obj - The object type to pick properties from
+ * @param keys - The keys to pick from the object
+ * @returns A runcheck type containing only the picked properties
+ * @throws Error if the input is not an object type
+ * @example
+ * ```typescript
+ * const userSchema = rc_object({ name: rc_string, age: rc_number, email: rc_string })
+ * const nameAndAge = rc_obj_pick(userSchema, ['name', 'age'])
+ * // Result: { name: string, age: number }
+ * ```
+ */
 declare function rc_obj_pick<O extends AnyObj, K extends keyof O>(obj: RcType<O>, keys: K[]): RcType<Pick<O, K>>;
+/**
+ * Creates a new object type without the specified properties from the original.
+ * @param obj - The object type to omit properties from
+ * @param keys - The keys to omit from the object
+ * @returns A runcheck type without the omitted properties
+ * @throws Error if the input is not an object type
+ * @example
+ * ```typescript
+ * const userSchema = rc_object({ name: rc_string, age: rc_number, email: rc_string })
+ * const withoutEmail = rc_obj_omit(userSchema, ['email'])
+ * // Result: { name: string, age: number }
+ * ```
+ */
 declare function rc_obj_omit<O extends AnyObj, K extends keyof O>(obj: RcType<O>, keys: K[]): RcType<Omit<O, K>>;
 type ExpectedSchema<T> = (t: T) => T;
 type RcTypeWithSchemaEqualTo<T> = {
@@ -71,16 +196,88 @@ type StrictTypeToRcType<T> = [
 type StrictTypeToRcTypeBase<T extends Record<string, any>> = {
     [K in keyof T]-?: StrictTypeToRcType<T[K]>;
 };
+/**
+ * Creates a type-safe object builder that enforces the structure matches a TypeScript type.
+ * Useful for creating schemas that must conform to existing TypeScript interfaces.
+ * @returns A builder function that takes a schema matching the specified TypeScript type
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string
+ *   age: number
+ *   email?: string
+ * }
+ *
+ * const userBuilder = rc_obj_builder<User>()
+ * const userSchema = userBuilder({
+ *   name: rc_string,
+ *   age: rc_number,
+ *   email: ['optional', rc_string]
+ * })
+ * ```
+ */
 declare function rc_obj_builder<T extends Record<string, any>>(): <S extends StrictTypeToRcTypeBase<T>>(schema: { [K in keyof S]: K extends keyof T ? S[K] : never; }, options?: ObjOptions) => RcType<T>;
 
+/**
+ * Creates a discriminated union type validator.
+ * Uses a discriminator key to determine which schema to validate against.
+ * @param discriminatorKey - The property name used to discriminate between union members
+ * @param types - An object mapping discriminator values to their corresponding schemas
+ * @returns A runcheck type that validates discriminated union objects
+ * @example
+ * ```typescript
+ * const shapeSchema = rc_discriminated_union('type', {
+ *   circle: { radius: rc_number },
+ *   rectangle: { width: rc_number, height: rc_number }
+ * })
+ *
+ * const result1 = shapeSchema.parse({ type: 'circle', radius: 5 }) // valid
+ * const result2 = shapeSchema.parse({ type: 'rectangle', width: 10, height: 20 }) // valid
+ * const result3 = shapeSchema.parse({ type: 'triangle', sides: 3 }) // invalid - unknown discriminator
+ * ```
+ */
 declare function rc_discriminated_union<K extends string, T extends Record<string, RcObject | RcBase<any, any>>>(discriminatorKey: K, types: T): RcType<Prettify<{
     [P in keyof T]: {
         [Q in K]: P;
     } & (T[P] extends RcType<infer U> ? U : T[P] extends RcObject ? TypeOfObjectType<T[P]> : never);
 }[keyof T]>>;
 type OmitDiscriminator<K, D extends Record<string, unknown>> = D extends any ? Omit<D, K & string> : never;
+/**
+ * Creates a type-safe discriminated union builder that enforces the structure matches a TypeScript type.
+ * @param discriminatorKey - The property name used to discriminate between union members
+ * @returns A builder function that takes a schema mapping matching the specified TypeScript discriminated union
+ * @example
+ * ```typescript
+ * type Shape =
+ *   | { type: 'circle', radius: number }
+ *   | { type: 'rectangle', width: number, height: number }
+ *
+ * const shapeBuilder = rc_discriminated_union_builder<Shape, 'type'>('type')
+ * const shapeSchema = shapeBuilder({
+ *   circle: { radius: rc_number },
+ *   rectangle: { width: rc_number, height: rc_number }
+ * })
+ * ```
+ */
 declare function rc_discriminated_union_builder<D extends Record<string, unknown>, K extends keyof D>(discriminatorKey: K): (schema: { [P in D[K] & string]: StrictTypeToRcTypeBase<OmitDiscriminator<K, D & { [Q in K]: P; }>>; }) => RcType<D>;
 
+/**
+ * Creates an intersection type validator that requires input to satisfy all provided types.
+ * For object types, merges the properties from all types.
+ * For non-object types, input must be valid for all types simultaneously.
+ * @param types - The types to intersect (2-4 types supported)
+ * @returns A runcheck type representing the intersection of all input types
+ * @example
+ * ```typescript
+ * const userBase = rc_object({ name: rc_string })
+ * const userMeta = rc_object({ createdAt: rc_date })
+ * const fullUser = rc_intersection(userBase, userMeta)
+ * // Result: { name: string, createdAt: Date }
+ *
+ * const result = fullUser.parse({ name: 'John', createdAt: new Date() }) // valid
+ * const result2 = fullUser.parse({ name: 'John' }) // invalid - missing createdAt
+ * ```
+ */
 declare function rc_intersection<A, B>(a: RcType<A>, b: RcType<B>): RcType<A & B>;
 declare function rc_intersection<A, B, C>(a: RcType<A>, b: RcType<B>, c: RcType<C>): RcType<A & B & C>;
 declare function rc_intersection<A, B, C, D>(a: RcType<A>, b: RcType<B>, c: RcType<C>, d: RcType<D>): RcType<A & B & C & D>;
@@ -179,29 +376,53 @@ type IsValid<T> = boolean | {
 };
 declare function parse<T>(type: RcType<T>, input: unknown, ctx: ParseResultCtx, checkIfIsValid: () => IsValid<T>): InternalParseResult<T>;
 declare const defaultProps: Omit<RcType<any>, '_parse_' | '_kind_'>;
+/** Equivalent to ts type: `undefined`. */
 declare const rc_undefined: RcType<undefined>;
+/** Equivalent to ts type: `null`. */
 declare const rc_null: RcType<null>;
+/** Equivalent to ts type: `any`. */
 declare const rc_any: RcType<any>;
+/** Equivalent to ts type: `unknown`. */
 declare const rc_unknown: RcType<unknown>;
+/** Equivalent to ts type: `boolean`. */
 declare const rc_boolean: RcType<boolean>;
+/** Equivalent to ts type: `string`. */
 declare const rc_string: RcType<string>;
+/** Equivalent to ts type: `number`. Excludes `NaN`. */
 declare const rc_number: RcType<number>;
+/** Equivalent to ts type: `Date`. Excludes invalid dates. */
 declare const rc_date: RcType<Date>;
-declare function rc_instanceof<T extends Function>(classToCheck: T): RcType<T>;
+/** Validates class instances using `instanceof` checks.
+ *
+ * @example
+ * ```typescript
+ * const userSchema = rc_instanceof(User) // schema is equivalent to `User` type
+ * const result = userSchema.parse(new User('John', 30)) // valid
+ * const result2 = userSchema.parse(new Admin('John', 30)) // invalid
+ * ```
+ */
+declare function rc_instanceof<T extends new (...args: any[]) => any>(classToCheck: T): RcType<InstanceType<T>>;
+/** Validates literal values like `'hello' | true | 1`. */
 declare function rc_literals<T extends (string | number | boolean)[]>(...literals: T): RcType<T[number]>;
+/** Validates union types like `string | number`. */
 declare function rc_union<T extends RcType<any>[]>(...types: T): RcType<RcInferType<T[number]>>;
 type NotUndefined<T> = Exclude<T, undefined>;
 /** Generate a schema with valid fallback value for undefined inputs */
+/** Provides default value for `undefined` inputs. */
 declare function rc_default<T>(schema: RcType<T>, defaultValue: NotUndefined<T> | (() => NotUndefined<T>)): RcType<NotUndefined<T>>;
 type NotNullish<T> = Exclude<T, null | undefined>;
+/** Provides default value for `null | undefined` inputs. */
 declare function rc_nullish_default<T>(schema: RcType<T>, defaultValue: NotNullish<T> | (() => NotNullish<T>)): RcType<NotNullish<T>>;
 /** returns a fallback in case of wrong inputs without adding a warning */
+/** Provides fallback value for invalid inputs without warnings. */
 declare function rc_safe_fallback<T>(schema: RcType<T>, fallback: NoInfer<T> | (() => NoInfer<T>)): RcType<T>;
+/** Validates `Record<string, T>`. Supports key validation and loose checking. */
 declare function rc_record<V>(valueType: RcType<V>, { checkKey, looseCheck, }?: {
     checkKey?: (key: string) => boolean;
     looseCheck?: boolean;
 }): RcType<Record<string, V>>;
 /** instead of returning a general error, rejects invalid keys and returns warnings for these items */
+/** Validates `Record<string, T>`. Filters out invalid values instead of rejecting. */
 declare function rc_loose_record<V>(valueType: RcType<V>, { checkKey }?: {
     checkKey?: (key: string) => boolean;
 }): RcType<Record<string, V>>;
@@ -211,13 +432,53 @@ type ArrayOptions<T extends RcType<any>> = {
         errors: ErrorWithPath[];
     };
 };
+/** Validates arrays of type `T[]`. Supports unique value checking. */
 declare function rc_array<T extends RcType<any>>(type: T, options?: ArrayOptions<T>): RcType<RcInferType<T>[]>;
+/**
+ * Extracts the item type from an array type.
+ * @param type - The array type to extract the item type from
+ * @returns The item type of the array
+ * @example
+ * ```typescript
+ * const stringArray = rc_array(rc_string)
+ * const itemType = rc_get_array_item_type(stringArray) // rc_string
+ * ```
+ */
 declare function rc_get_array_item_type<T>(type: RcType<T[]>): RcType<T>;
+/**
+ * Disables loose array validation for a type.
+ * @param type - The type to modify
+ * @param options - Configuration options
+ * @param options.nonRecursive - If true, only affects the immediate array type
+ * @returns The modified type with loose array validation disabled
+ * @example
+ * ```typescript
+ * const strictArray = rc_disable_loose_array(rc_array(rc_string))
+ * ```
+ */
 declare function rc_disable_loose_array<T extends RcType<any>>(type: T, { nonRecursive }?: {
     nonRecursive?: boolean;
 }): T;
 /** instead of returning a general error, rejects invalid array items and returns warnings for these items */
+/** Validates arrays of type `T[]`. Filters out invalid elements instead of rejecting the array. */
 declare function rc_loose_array<T extends RcType<any>>(type: T, options?: ArrayOptions<T>): RcType<RcInferType<T>[]>;
+/**
+ * Creates an array validator with schema-based filtering.
+ * @param filterSchema - The schema to validate items before filtering
+ * @param filterFn - The function to determine if validated items should be included
+ * @param type - The type to validate for included array elements
+ * @param options - Configuration options
+ * @returns A runcheck type that validates and filters arrays based on the schema
+ * @example
+ * ```typescript
+ * const evenNumbers = rc_array_filter_from_schema(
+ *   rc_number,
+ *   (n) => n % 2 === 0,
+ *   rc_number
+ * )
+ * const result = evenNumbers.parse([1, 2, 3, 4]) // returns [2, 4]
+ * ```
+ */
 declare function rc_array_filter_from_schema<B, T>(filterSchema: RcType<B>, filterFn: (item: B) => boolean, type: RcType<T>, options?: Omit<ArrayOptions<RcType<any>>, 'filter'> & {
     loose?: boolean;
 }): RcType<T[]>;
@@ -229,6 +490,7 @@ type MapTupleToTypes<T extends readonly [...any[]]> = {
  *
  * TS equivalent example: [string, number, boolean]
  */
+/** Validates tuples like `[T, T]` with fixed length. */
 declare function rc_tuple<const T extends readonly RcType<any>[]>(types: T): RcType<MapTupleToTypes<T>>;
 type ParseOptions = {
     /** ignore fallback and autofix */
@@ -238,9 +500,37 @@ type ParseOptions = {
  * Parse a runcheck type. If valid return the valid input, with warning for autofix
  * and fallback, or the errors if invalid
  */
+/**
+ * Parses and validates input against a runcheck type schema.
+ * @param input - The input value to validate
+ * @param type - The runcheck type schema to validate against
+ * @param options - Parse options
+ * @param options.noWarnings - If true, disables fallback and autofix warnings
+ * @returns The parse result containing either the validated value or errors
+ * @example
+ * ```typescript
+ * const result = rc_parse('hello', rc_string)
+ * if (result.ok) {
+ *   console.log(result.value) // 'hello'
+ * } else {
+ *   console.log(result.errors) // validation errors
+ * }
+ * ```
+ */
 declare function rc_parse<S>(input: any, type: RcType<S>, { noWarnings }?: ParseOptions): RcParseResult<S>;
 type RcParser<T> = (input: any) => RcParseResult<T>;
 /** create a reusable parser for a certain type */
+/**
+ * Creates a reusable parser function for a runcheck type.
+ * @param type - The runcheck type to create a parser for
+ * @returns A parser function that can be called with input values
+ * @example
+ * ```typescript
+ * const parseString = rc_parser(rc_string)
+ * const result1 = parseString('hello')
+ * const result2 = parseString(123)
+ * ```
+ */
 declare function rc_parser<S>(type: RcType<S>): RcParser<S>;
 /** @deprecated use rc_unwrap_or_null instead */
 declare function rc_loose_parse<S>(input: any, type: RcType<S>, options?: ParseOptions): {
@@ -270,8 +560,53 @@ declare function rc_unwrap<R>(result: RcParseResult<R>): {
     value: R;
     warnings: string[] | false;
 };
+/**
+ * Type guard function that checks if input is valid for a given type.
+ * @param input - The input value to validate
+ * @param type - The runcheck type to validate against
+ * @returns True if input is valid, false otherwise (with type narrowing)
+ * @example
+ * ```typescript
+ * if (rc_is_valid(input, rc_string)) {
+ *   // input is now typed as string
+ *   console.log(input.toUpperCase())
+ * }
+ * ```
+ */
 declare function rc_is_valid<S>(input: any, type: RcType<S>): input is S;
+/**
+ * Creates a validator function that acts as a type guard.
+ * @param type - The runcheck type to create a validator for
+ * @returns A validator function that can be used as a type guard
+ * @example
+ * ```typescript
+ * const isString = rc_validator(rc_string)
+ * if (isString(input)) {
+ *   // input is now typed as string
+ *   console.log(input.length)
+ * }
+ * ```
+ */
 declare function rc_validator<S>(type: RcType<S>): (input: any) => input is S;
+/**
+ * Creates a recursive type definition for self-referencing data structures.
+ * @param type - A function that returns the recursive type definition
+ * @returns A runcheck type that can handle recursive structures
+ * @example
+ * ```typescript
+ * type TreeNode = {
+ *   value: string
+ *   children?: TreeNode[]
+ * }
+ *
+ * const TreeNode: RcType<TreeNode> = rc_recursive(() =>
+ *   rc_object({
+ *     value: rc_string,
+ *     children: rc_array(TreeNode).optional(),
+ *   })
+ * )
+ * ```
+ */
 declare function rc_recursive<T extends RcBase<any, any>>(type: () => T): T;
 type TransformOptions<T> = {
     /**
@@ -285,10 +620,62 @@ type TransformOptions<T> = {
     disableStrictOutputSchema?: boolean;
 };
 /** validate a input or subset of input and transform the valid result */
+/**
+ * Creates a type that validates input and transforms the result.
+ * @param type - The input type to validate against
+ * @param transform - Function to transform the validated input
+ * @param options - Transform options
+ * @param options.outputSchema - Optional schema to validate the transformed output
+ * @param options.disableStrictOutputSchema - If true, allows loose validation of output
+ * @returns A runcheck type that validates input and applies transformation
+ * @example
+ * ```typescript
+ * const upperCaseString = rc_transform(
+ *   rc_string,
+ *   (str) => str.toUpperCase()
+ * )
+ * const result = upperCaseString.parse('hello') // returns 'HELLO'
+ * ```
+ */
 declare function rc_transform<Input, Transformed>(type: RcType<Input>, transform: (input: Input, inputSchema: RcType<Input>) => Transformed, { outputSchema, disableStrictOutputSchema, }?: TransformOptions<Transformed>): RcType<Transformed>;
 /** Create transforms which result can be validated with the same schema */
+/**
+ * Creates a narrowing transformation that refines the input type.
+ * @param type - The input type to validate against
+ * @param narrow - Function to narrow the validated input to a more specific type
+ * @returns A runcheck type that validates and narrows the input
+ * @example
+ * ```typescript
+ * const positiveNumber = rc_narrow(
+ *   rc_number,
+ *   (n) => n > 0 ? n : 0
+ * )
+ * ```
+ */
 declare function rc_narrow<Input, Narrowed extends Input>(type: RcType<Input>, narrow: (input: Input, inputSchema: RcType<Input>) => Narrowed): RcType<Narrowed>;
 /** Allows the transform function to return a error if transformation is invalid */
+/**
+ * Creates a transformation that can fail with custom error messages.
+ * @param type - The input type to validate against
+ * @param transform - Function that returns either transformed data or errors
+ * @param options - Transform options
+ * @param options.outputSchema - Optional schema to validate the transformed output
+ * @param options.disableStrictOutputSchema - If true, allows loose validation of output
+ * @returns A runcheck type that validates input and applies fallible transformation
+ * @example
+ * ```typescript
+ * const parseJson = rc_unsafe_transform(
+ *   rc_string,
+ *   (str) => {
+ *     try {
+ *       return { ok: true, data: JSON.parse(str) }
+ *     } catch {
+ *       return { ok: false, errors: 'Invalid JSON' }
+ *     }
+ *   }
+ * )
+ * ```
+ */
 declare function rc_unsafe_transform<Input, Transformed>(type: RcType<Input>, transform: (input: Input, inputSchema: RcType<Input>) => {
     ok: true;
     data: Transformed;
@@ -297,6 +684,18 @@ declare function rc_unsafe_transform<Input, Transformed>(type: RcType<Input>, tr
     errors: string | string[];
 }, { outputSchema, disableStrictOutputSchema, }?: TransformOptions<Transformed>): RcType<Transformed>;
 declare function normalizedTypeOf(input: unknown, showValueInError: boolean): string;
+/**
+ * Assertion function that throws if the parse result contains errors.
+ * @param result - The parse result to assert validity for
+ * @throws Error if the result contains validation errors
+ * @example
+ * ```typescript
+ * const result = rc_parse(input, rc_string)
+ * rc_assert_is_valid(result)
+ * // result is now typed as successful result
+ * console.log(result.value)
+ * ```
+ */
 declare function rc_assert_is_valid<S>(result: RcParseResult<S>): asserts result is {
     ok: true;
     error: false;
@@ -308,18 +707,88 @@ declare function rc_assert_is_valid<S>(result: RcParseResult<S>): asserts result
     unwrapOr: (defaultValue: S) => S;
     unwrapOrNull: () => S | null;
 };
+/**
+ * Parses a JSON string and validates it against a schema.
+ * @param jsonString - The JSON string to parse
+ * @param schema - The runcheck type to validate the parsed JSON against
+ * @param options - Parse options
+ * @returns The parse result containing either the validated JSON value or errors
+ * @example
+ * ```typescript
+ * const userSchema = rc_object({ name: rc_string, age: rc_number })
+ * const result = rc_parse_json('{"name":"John","age":30}', userSchema)
+ * ```
+ */
 declare function rc_parse_json<T>(jsonString: unknown, schema: RcType<T>, options?: ParseOptions): RcParseResult<T>;
 type Prettify<T> = T extends Record<string, any> ? {
     [K in keyof T]: Prettify<T[K]>;
 } : T;
 type RcPrettyInferType<T extends RcType<any>> = Prettify<RcInferType<T>>;
+/**
+ * Type guard function that checks if a value is a runcheck type.
+ * @param value - The value to check
+ * @returns True if the value is a runcheck type, false otherwise
+ * @example
+ * ```typescript
+ * if (isRcType(someValue)) {
+ *   // someValue is now typed as RcType<any>
+ *   const result = someValue.parse(input)
+ * }
+ * ```
+ */
 declare function isRcType(value: any): value is RcType<any>;
 /** workaround for the typescript limitation: https://github.com/microsoft/TypeScript/issues/52295 */
+/**
+ * Workaround for TypeScript limitation with union types.
+ * @param type - The type to cast as a union type
+ * @returns The type cast as a proper runcheck union type
+ * @example
+ * ```typescript
+ * const unionType = joinAsRcTypeUnion(someComplexUnionType)
+ * ```
+ */
 declare function joinAsRcTypeUnion<T>(type: T): RcType<T extends RcType<infer U> ? U : never>;
+/**
+ * Gets the kind/name of a runcheck schema for debugging purposes.
+ * @param schema - The runcheck type to get the kind from
+ * @returns The string representation of the schema kind
+ * @example
+ * ```typescript
+ * const kind = getSchemaKind(rc_string) // returns 'string'
+ * const kind2 = getSchemaKind(rc_array(rc_number)) // returns 'number[]'
+ * ```
+ */
 declare function getSchemaKind(schema: RcType<any>): string;
+/**
+ * Converts a runcheck type or parse result to a Standard Schema V1.
+ * @param schemaOrResult - The runcheck type or parse result to convert
+ * @param options - Conversion options
+ * @param options.errorOnWarnings - If true, treat warnings as errors
+ * @param options.onWarnings - Callback function to handle warnings
+ * @returns A Standard Schema V1 compatible object
+ * @example
+ * ```typescript
+ * const standardSchema = rc_to_standard(rc_string)
+ * const result = standardSchema['~standard'].validate('hello')
+ * ```
+ */
 declare function rc_to_standard<T>(schemaOrResult: RcType<T> | RcParseResult<T>, { errorOnWarnings, onWarnings, }?: {
     errorOnWarnings?: boolean;
     onWarnings?: (warnings: string[]) => void;
 }): StandardSchemaV1<T>;
+/**
+ * Converts a Standard Schema V1 to a runcheck type.
+ * @param standardSchema - The Standard Schema V1 to convert
+ * @param kind - Optional custom kind name for error messages
+ * @returns A runcheck type that wraps the standard schema
+ * @example
+ * ```typescript
+ * const rcType = rc_from_standard(someStandardSchema)
+ * const result = rcType.parse(input)
+ * ```
+ */
+declare function rc_from_standard<T>(standardSchema: StandardSchemaV1<any, T>, 
+/** use this kind instead of the default one in error messages (standard_schema_${standard.vendor}@${standard.version}) */
+kind?: string): RcType<T>;
 
-export { type AutoFixResult, type Prettify, type RcBase, type RcErrorResult, type RcInferType, type RcOkResult, type RcOptionalKeyType, type RcParseResult, type RcParser, type RcPrettyInferType, type RcType, RcValidationError, defaultProps, getSchemaKind, getWarningOrErrorWithPath, isRcType, joinAsRcTypeUnion, normalizedTypeOf, parse, rc_any, rc_array, rc_array_filter_from_schema, rc_assert_is_valid, rc_boolean, rc_date, rc_default, rc_disable_loose_array, rc_discriminated_union, rc_discriminated_union_builder, rc_enable_obj_strict, rc_get_array_item_type, rc_get_from_key_as_fallback, rc_get_obj_shape, rc_instanceof, rc_intersection, rc_is_valid, rc_literals, rc_loose_array, rc_loose_parse, rc_loose_record, rc_narrow, rc_null, rc_nullish_default, rc_number, rc_obj_builder, rc_obj_extends, rc_obj_merge, rc_obj_omit, rc_obj_pick, rc_obj_strict, rc_object, rc_parse, rc_parse_json, rc_parser, rc_record, rc_recursive, rc_safe_fallback, rc_string, rc_to_standard, rc_transform, rc_tuple, rc_undefined, rc_union, rc_unknown, rc_unsafe_transform, rc_unwrap, rc_unwrap_or, rc_unwrap_or_null, rc_validator };
+export { type AutoFixResult, type Prettify, type RcBase, type RcErrorResult, type RcInferType, type RcOkResult, type RcOptionalKeyType, type RcParseResult, type RcParser, type RcPrettyInferType, type RcType, RcValidationError, defaultProps, getSchemaKind, getWarningOrErrorWithPath, isRcType, joinAsRcTypeUnion, normalizedTypeOf, parse, rc_any, rc_array, rc_array_filter_from_schema, rc_assert_is_valid, rc_boolean, rc_date, rc_default, rc_disable_loose_array, rc_discriminated_union, rc_discriminated_union_builder, rc_enable_obj_strict, rc_from_standard, rc_get_array_item_type, rc_get_from_key_as_fallback, rc_get_obj_shape, rc_instanceof, rc_intersection, rc_is_valid, rc_literals, rc_loose_array, rc_loose_parse, rc_loose_record, rc_narrow, rc_null, rc_nullish_default, rc_number, rc_obj_builder, rc_obj_extends, rc_obj_merge, rc_obj_omit, rc_obj_pick, rc_obj_strict, rc_object, rc_parse, rc_parse_json, rc_parser, rc_record, rc_recursive, rc_safe_fallback, rc_string, rc_to_standard, rc_transform, rc_tuple, rc_undefined, rc_union, rc_unknown, rc_unsafe_transform, rc_unwrap, rc_unwrap_or, rc_unwrap_or_null, rc_validator };

package/dist/runcheck.js

@@ -1,2 +1,2 @@
-import{$,A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,_,a,aa,b,ba,c,ca,d,da,e,ea,f,fa,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z}from"./chunk-UNFQGHGF.js";export{R as RcValidationError,p as defaultProps,ea as getSchemaKind,n as getWarningOrErrorWithPath,$ as isObject,ca as isRcType,da as joinAsRcTypeUnion,Z as normalizedTypeOf,o as parse,s as rc_any,G as rc_array,K as rc_array_filter_from_schema,_ as rc_assert_is_valid,u as rc_boolean,x as rc_date,B as rc_default,I as rc_disable_loose_array,k as rc_discriminated_union,l as rc_discriminated_union_builder,f as rc_enable_obj_strict,H as rc_get_array_item_type,a as rc_get_from_key_as_fallback,d as rc_get_obj_shape,y as rc_instanceof,m as rc_intersection,T as rc_is_valid,z as rc_literals,J as rc_loose_array,O as rc_loose_parse,F as rc_loose_record,X as rc_narrow,r as rc_null,C as rc_nullish_default,w as rc_number,j as rc_obj_builder,c as rc_obj_extends,g as rc_obj_merge,i as rc_obj_omit,h as rc_obj_pick,e as rc_obj_strict,b as rc_object,M as rc_parse,ba as rc_parse_json,N as rc_parser,E as rc_record,V as rc_recursive,D as rc_safe_fallback,v as rc_string,fa as rc_to_standard,W as rc_transform,L as rc_tuple,q as rc_undefined,A as rc_union,t as rc_unknown,Y as rc_unsafe_transform,S as rc_unwrap,Q as rc_unwrap_or,P as rc_unwrap_or_null,U as rc_validator,aa as snakeCase};
+import{$,A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,_,a,aa,b,ba,c,ca,d,da,e,ea,f,fa,g,ga,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z}from"./chunk-WENGZHOX.js";export{R as RcValidationError,p as defaultProps,ea as getSchemaKind,n as getWarningOrErrorWithPath,$ as isObject,ca as isRcType,da as joinAsRcTypeUnion,Z as normalizedTypeOf,o as parse,s as rc_any,G as rc_array,K as rc_array_filter_from_schema,_ as rc_assert_is_valid,u as rc_boolean,x as rc_date,B as rc_default,I as rc_disable_loose_array,k as rc_discriminated_union,l as rc_discriminated_union_builder,f as rc_enable_obj_strict,ga as rc_from_standard,H as rc_get_array_item_type,a as rc_get_from_key_as_fallback,d as rc_get_obj_shape,y as rc_instanceof,m as rc_intersection,T as rc_is_valid,z as rc_literals,J as rc_loose_array,O as rc_loose_parse,F as rc_loose_record,X as rc_narrow,r as rc_null,C as rc_nullish_default,w as rc_number,j as rc_obj_builder,c as rc_obj_extends,g as rc_obj_merge,i as rc_obj_omit,h as rc_obj_pick,e as rc_obj_strict,b as rc_object,M as rc_parse,ba as rc_parse_json,N as rc_parser,E as rc_record,V as rc_recursive,D as rc_safe_fallback,v as rc_string,fa as rc_to_standard,W as rc_transform,L as rc_tuple,q as rc_undefined,A as rc_union,t as rc_unknown,Y as rc_unsafe_transform,S as rc_unwrap,Q as rc_unwrap_or,P as rc_unwrap_or_null,U as rc_validator,aa as snakeCase};
 //# sourceMappingURL=runcheck.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "runcheck",
   "description": "A tiny (less than 2 KiB Gzipped) and treeshakable! lib for typescript runtime type checks with autofix support",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "license": "MIT",
   "files": [
     "dist"
@@ -53,7 +53,7 @@
     "valibot": "^0.41.0",
     "vite": "^5.4.3",
     "vitest": "^2.0.5",
-    "zod": "^3.23.8"
+    "zod": "^3.25.75"
   },
   "scripts": {
     "test:watch": "vitest --ui --typecheck",