wellcrafted/dist/standard-schema/index.d.ts

Delightful TypeScript patterns for elegant, type-safe applications

//#region src/standard-schema/types.d.ts
/**
 * Standard Schema type definitions.
 *
 * These interfaces are copied from the Standard Schema specification
 * (https://standardschema.dev) to avoid external dependencies.
 *
 * @see https://github.com/standard-schema/standard-schema
 */
/**
 * The Standard Typed interface. This is a base type extended by other specs.
 */
type StandardTypedV1<Input = unknown, Output = Input> = {
  /** The Standard properties. */
  readonly "~standard": StandardTypedV1.Props<Input, Output>;
};
declare namespace StandardTypedV1 {
  /** The Standard Typed properties interface. */
  type Props<Input = unknown, Output = Input> = {
    /** The version number of the standard. */
    readonly version: 1;
    /** The vendor name of the schema library. */
    readonly vendor: string;
    /** Inferred types associated with the schema. */
    readonly types?: Types<Input, Output> | undefined;
  };
  /** The Standard Typed types interface. */
  type Types<Input = unknown, Output = Input> = {
    /** The input type of the schema. */
    readonly input: Input;
    /** The output type of the schema. */
    readonly output: Output;
  };
  /** Infers the input type of a Standard Typed. */
  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
  /** Infers the output type of a Standard Typed. */
  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
}
/**
 * The Standard Schema interface.
 *
 * Extends StandardTypedV1 with a validate function for runtime validation.
 */
type StandardSchemaV1<Input = unknown, Output = Input> = {
  /** The Standard Schema properties. */
  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
};
declare namespace StandardSchemaV1 {
  /** The Standard Schema properties interface. */
  type Props<Input = unknown, Output = Input> = StandardTypedV1.Props<Input, Output> & {
    /** Validates unknown input values. */
    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
  };
  /** The result interface of the validate function. */
  type Result<Output> = SuccessResult<Output> | FailureResult;
  /** The result interface if validation succeeds. */
  type SuccessResult<Output> = {
    /** The typed output value. */
    readonly value: Output;
    /** A falsy value for `issues` indicates success. */
    readonly issues?: undefined;
  };
  /** Options for the validate function. */
  type Options = {
    /** Explicit support for additional vendor-specific parameters, if needed. */
    readonly libraryOptions?: Record<string, unknown> | undefined;
  };
  /** The result interface if validation fails. */
  type FailureResult = {
    /** The issues of failed validation. */
    readonly issues: ReadonlyArray<Issue>;
  };
  /** The issue interface of the failure output. */
  type Issue = {
    /** The error message of the issue. */
    readonly message: string;
    /** The path of the issue, if any. */
    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
  };
  /** The path segment interface of the issue. */
  type PathSegment = {
    /** The key representing a path segment. */
    readonly key: PropertyKey;
  };
  /** Infers the input type of a Standard Schema. */
  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
  /** Infers the output type of a Standard Schema. */
  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
}
/**
 * The Standard JSON Schema interface.
 *
 * Extends StandardTypedV1 with methods for generating JSON Schema.
 */
type StandardJSONSchemaV1<Input = unknown, Output = Input> = {
  /** The Standard JSON Schema properties. */
  readonly "~standard": StandardJSONSchemaV1.Props<Input, Output>;
};
declare namespace StandardJSONSchemaV1 {
  /** The Standard JSON Schema properties interface. */
  type Props<Input = unknown, Output = Input> = StandardTypedV1.Props<Input, Output> & {
    /** Methods for generating the input/output JSON Schema. */
    readonly jsonSchema: StandardJSONSchemaV1.Converter;
  };
  /** The Standard JSON Schema converter interface. */
  type Converter = {
    /** Converts the input type to JSON Schema. May throw if conversion is not supported. */
    readonly input: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
    /** Converts the output type to JSON Schema. May throw if conversion is not supported. */
    readonly output: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
  };
  /**
   * The target version of the generated JSON Schema.
   *
   * It is *strongly recommended* that implementers support `"draft-2020-12"` and `"draft-07"`,
   * as they are both in wide use. All other targets can be implemented on a best-effort basis.
   * Libraries should throw if they don't support a specified target.
   *
   * The `"openapi-3.0"` target is intended as a standardized specifier for OpenAPI 3.0
   * which is a superset of JSON Schema `"draft-04"`.
   */
  type Target = "draft-2020-12" | "draft-07" | "openapi-3.0" | (string & {});
  /** The options for the input/output methods. */
  type Options = {
    /** Specifies the target version of the generated JSON Schema. */
    readonly target: Target;
    /** Explicit support for additional vendor-specific parameters, if needed. */
    readonly libraryOptions?: Record<string, unknown> | undefined;
  };
  /** Infers the input type of a Standard JSON Schema. */
  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
  /** Infers the output type of a Standard JSON Schema. */
  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
}
/**
 * Checks if a schema has validation capability.
 */
declare function hasValidate<T extends StandardTypedV1>(schema: T): schema is T & StandardSchemaV1;
/**
 * Checks if a schema has JSON Schema generation capability.
 */
declare function hasJsonSchema<T extends StandardTypedV1>(schema: T): schema is T & StandardJSONSchemaV1;
//# sourceMappingURL=types.d.ts.map
//#endregion
//#region src/standard-schema/err.d.ts
/**
 * Output type for ErrSchema - wraps inner schema's types with Err structure.
 *
 * Preserves the capabilities of the input schema:
 * - If input has validate, output has validate
 * - If input has jsonSchema, output has jsonSchema
 */
type Err<TSchema extends StandardTypedV1> = {
  readonly "~standard": {
    readonly version: 1;
    readonly vendor: "wellcrafted";
    readonly types: {
      readonly input: {
        data: null;
        error: StandardTypedV1.InferInput<TSchema>;
      };
      readonly output: {
        data: null;
        error: StandardTypedV1.InferOutput<TSchema>;
      };
    };
  } & (TSchema extends StandardSchemaV1 ? {
    readonly validate: StandardSchemaV1.Props<{
      data: null;
      error: StandardTypedV1.InferInput<TSchema>;
    }, {
      data: null;
      error: StandardTypedV1.InferOutput<TSchema>;
    }>["validate"];
  } : Record<string, never>) & (TSchema extends StandardJSONSchemaV1 ? {
    readonly jsonSchema: StandardJSONSchemaV1.Converter;
  } : Record<string, never>);
};
/**
 * Wraps a Standard Schema into an Err variant schema.
 *
 * Takes a schema for type E and returns a schema for `{ data: null, error: E }`.
 * Preserves the capabilities of the input schema (validate, jsonSchema, or both).
 *
 * @example
 * ```typescript
 * import { z } from "zod";
 * import { ErrSchema } from "wellcrafted/standard-schema";
 *
 * const errorSchema = z.object({ code: z.string(), message: z.string() });
 * const errResultSchema = ErrSchema(errorSchema);
 *
 * // Validates: { data: null, error: { code: "NOT_FOUND", message: "User not found" } }
 * const result = errResultSchema["~standard"].validate({
 *   data: null,
 *   error: { code: "NOT_FOUND", message: "User not found" },
 * });
 * ```
 */
declare function ErrSchema<TSchema extends StandardTypedV1>(innerSchema: TSchema): Err<TSchema>;
//# sourceMappingURL=err.d.ts.map
//#endregion
//#region src/standard-schema/failures.d.ts
declare const FAILURES: {
  readonly EXPECTED_OBJECT: {
    readonly issues: readonly [{
      readonly message: "Expected object";
    }];
  };
  readonly EXPECTED_DATA_ERROR_PROPS: {
    readonly issues: readonly [{
      readonly message: "Expected object with 'data' and 'error' properties";
    }];
  };
  readonly EXPECTED_ERROR_NULL: {
    readonly issues: readonly [{
      readonly message: "Expected 'error' to be null for Ok variant";
      readonly path: readonly ["error"];
    }];
  };
  readonly EXPECTED_ERROR_NOT_NULL: {
    readonly issues: readonly [{
      readonly message: "Expected 'error' to be non-null for Err variant";
      readonly path: readonly ["error"];
    }];
  };
};
//# sourceMappingURL=failures.d.ts.map
//#endregion
//#region src/standard-schema/ok.d.ts
/**
 * Output type for OkSchema - wraps inner schema's types with Ok structure.
 *
 * Preserves the capabilities of the input schema:
 * - If input has validate, output has validate
 * - If input has jsonSchema, output has jsonSchema
 */
type Ok<TSchema extends StandardTypedV1> = {
  readonly "~standard": {
    readonly version: 1;
    readonly vendor: "wellcrafted";
    readonly types: {
      readonly input: {
        data: StandardTypedV1.InferInput<TSchema>;
        error: null;
      };
      readonly output: {
        data: StandardTypedV1.InferOutput<TSchema>;
        error: null;
      };
    };
  } & (TSchema extends StandardSchemaV1 ? {
    readonly validate: StandardSchemaV1.Props<{
      data: StandardTypedV1.InferInput<TSchema>;
      error: null;
    }, {
      data: StandardTypedV1.InferOutput<TSchema>;
      error: null;
    }>["validate"];
  } : Record<string, never>) & (TSchema extends StandardJSONSchemaV1 ? {
    readonly jsonSchema: StandardJSONSchemaV1.Converter;
  } : Record<string, never>);
};
/**
 * Wraps a Standard Schema into an Ok variant schema.
 *
 * Takes a schema for type T and returns a schema for `{ data: T, error: null }`.
 * Preserves the capabilities of the input schema (validate, jsonSchema, or both).
 *
 * @example
 * ```typescript
 * import { z } from "zod";
 * import { OkSchema } from "wellcrafted/standard-schema";
 *
 * const userSchema = z.object({ name: z.string() });
 * const okUserSchema = OkSchema(userSchema);
 *
 * // Validates: { data: { name: "Alice" }, error: null }
 * const result = okUserSchema["~standard"].validate({
 *   data: { name: "Alice" },
 *   error: null,
 * });
 * ```
 */
declare function OkSchema<TSchema extends StandardTypedV1>(innerSchema: TSchema): Ok<TSchema>;
//# sourceMappingURL=ok.d.ts.map
//#endregion
//#region src/standard-schema/result.d.ts
/**
 * Output type for ResultSchema - creates a discriminated union of Ok and Err.
 *
 * Preserves the capabilities of the input schemas:
 * - If both inputs have validate, output has validate
 * - If both inputs have jsonSchema, output has jsonSchema
 */
type Result$1<TDataSchema extends StandardTypedV1, TErrorSchema extends StandardTypedV1> = {
  readonly "~standard": {
    readonly version: 1;
    readonly vendor: "wellcrafted";
    readonly types: {
      readonly input: {
        data: StandardTypedV1.InferInput<TDataSchema>;
        error: null;
      } | {
        data: null;
        error: StandardTypedV1.InferInput<TErrorSchema>;
      };
      readonly output: {
        data: StandardTypedV1.InferOutput<TDataSchema>;
        error: null;
      } | {
        data: null;
        error: StandardTypedV1.InferOutput<TErrorSchema>;
      };
    };
  } & (TDataSchema extends StandardSchemaV1 ? TErrorSchema extends StandardSchemaV1 ? {
    readonly validate: StandardSchemaV1.Props<{
      data: StandardTypedV1.InferInput<TDataSchema>;
      error: null;
    } | {
      data: null;
      error: StandardTypedV1.InferInput<TErrorSchema>;
    }, {
      data: StandardTypedV1.InferOutput<TDataSchema>;
      error: null;
    } | {
      data: null;
      error: StandardTypedV1.InferOutput<TErrorSchema>;
    }>["validate"];
  } : Record<string, never> : Record<string, never>) & (TDataSchema extends StandardJSONSchemaV1 ? TErrorSchema extends StandardJSONSchemaV1 ? {
    readonly jsonSchema: StandardJSONSchemaV1.Converter;
  } : Record<string, never> : Record<string, never>);
};
/**
 * Combines two Standard Schemas into a Result discriminated union schema.
 *
 * Takes a data schema for type T and an error schema for type E, returning a schema
 * for `{ data: T, error: null } | { data: null, error: E }`.
 *
 * Preserves the capabilities of the input schemas - if both have validate, output
 * has validate; if both have jsonSchema, output has jsonSchema.
 *
 * @example
 * ```typescript
 * import { z } from "zod";
 * import { ResultSchema } from "wellcrafted/standard-schema";
 *
 * const userSchema = z.object({ id: z.string(), name: z.string() });
 * const errorSchema = z.object({ code: z.string(), message: z.string() });
 * const resultSchema = ResultSchema(userSchema, errorSchema);
 *
 * // Validates Ok variant: { data: { id: "1", name: "Alice" }, error: null }
 * // Validates Err variant: { data: null, error: { code: "NOT_FOUND", message: "..." } }
 * const result = resultSchema["~standard"].validate({
 *   data: { id: "1", name: "Alice" },
 *   error: null,
 * });
 * ```
 */
declare function ResultSchema<TDataSchema extends StandardTypedV1, TErrorSchema extends StandardTypedV1>(dataSchema: TDataSchema, errorSchema: TErrorSchema): Result$1<TDataSchema, TErrorSchema>;
//# sourceMappingURL=result.d.ts.map

//#endregion
export { Err, ErrSchema, FAILURES, Ok, OkSchema, Result$1 as Result, ResultSchema, StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1, hasJsonSchema, hasValidate };
//# sourceMappingURL=index.d.ts.map