runcheck 1.12.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,19 +707,86 @@ 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>;

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,ga,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z}from"./chunk-QNKGO7DW.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};
+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.12.0",
+  "version": "1.13.0",
   "license": "MIT",
   "files": [
     "dist"