@socketsecurity/lib 5.20.1 → 5.21.0

package/dist/validation/validate-schema.d.ts

@@ -1,124 +0,0 @@
-/**
- * @fileoverview Universal schema validation for Zod-style schemas (Zod v3,
- * v4, and any `safeParse`-shaped duck type).
- *
- * Accepts a schema and returns a tagged result.
- *   - `{ ok: true, value }`  — validation passed, `value` is typed as the
- *     schema's inferred output (`z.infer<typeof S>`).
- *   - `{ ok: false, errors }` — validation failed, `errors` is a normalized
- *     list of `{ path, message }`.
- *
- * Zod is detected purely structurally via `.safeParse` — no runtime import of
- * the `zod` package is required by socket-lib.
- *
- * @internal
- * Socket-lib additionally recognizes TypeBox schemas for its own internal
- * use (e.g. `src/ipc.ts`'s stub-file validation). That path is not a
- * supported consumer API — callers should use Zod.
- */
-import type { Schema } from './types';
-/**
- * TypeBox's `Kind` symbol. We reference it structurally for schema detection
- * rather than importing it from `@sinclair/typebox` — detection scans the
- * schema's own-symbol keys for one whose description is `'TypeBox.Kind'`.
- * The `Value` runtime is only loaded lazily when a TypeBox schema is seen.
- */
-type TypeBoxKindSymbol = symbol & {
-    __typeBoxKindBrand?: never;
-};
-/**
- * Structural minimum of a TypeBox `TSchema`. The phantom `static` field is
- * the type TypeBox uses for inference (`Static<T> = T['static']`).
- */
-interface TypeBoxLikeSchema {
-    [k: TypeBoxKindSymbol]: string;
-    static: unknown;
-}
-/**
- * Structural shape of a Zod v4 schema — carries output type on `_zod.output`.
- */
-interface ZodV4LikeSchema<O = unknown> {
-    _zod: {
-        output: O;
-    };
-    safeParse(data: unknown): unknown;
-}
-/**
- * Structural shape of a Zod v3 schema — carries output type on `_output`.
- */
-interface ZodV3LikeSchema<O = unknown> {
-    _output: O;
-    safeParse(data: unknown): unknown;
-}
-/**
- * Any schema kind this helper accepts.
- */
-export type AnySchema = TypeBoxLikeSchema | ZodV4LikeSchema<unknown> | ZodV3LikeSchema<unknown> | Schema<unknown>;
-/**
- * Infer the validated output type from any supported schema kind.
- *
- * Order matters: TypeBox schemas also carry a phantom `static` field, so we
- * check for TypeBox before falling through to Zod and the duck-type.
- */
-export type Infer<S> = S extends {
-    static: infer Static;
-} ? Static : S extends {
-    _zod: {
-        output: infer O;
-    };
-} ? O : S extends {
-    _output: infer O;
-} ? O : S extends Schema<infer T> ? T : unknown;
-/**
- * A single normalized validation error.
- * - `path` is a dotted or slash-separated identifier locating the bad value.
- * - `message` is human-readable.
- */
-export interface ValidationIssue {
-    /** Array path into the value (e.g. `['user', 'age']`). */
-    path: Array<string | number>;
-    /** Human-readable description of the failure. */
-    message: string;
-}
-/**
- * Tagged-union result of {@link validateSchema}. Callers narrow on `ok`.
- */
-export type ValidateResult<T> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    errors: ValidationIssue[];
-};
-/**
- * Validate `data` against a Zod-style `schema`. Non-throwing.
- *
- * Accepted schemas:
- * - `zod` schemas, v3 and v4 (detected via `.safeParse` on the schema)
- * - Any object conforming to {@link Schema} (the socket-lib duck type)
- *
- * The return type narrows `value` to {@link Infer | `Infer<S>`}, so callers
- * get `z.infer<typeof S>` with no casts.
- *
- * @example
- * ```ts
- * import { z } from 'zod'
- * const U = z.object({ name: z.string() })
- * const r = validateSchema(U, data)
- * if (r.ok) r.value.name // string
- * ```
- *
- * Errors are normalized to {@link ValidationIssue}: `{ path, message }`.
- */
-export declare function validateSchema<S>(schema: S, data: unknown): ValidateResult<Infer<S>>;
-/**
- * Parse `data` against `schema` and return the validated value. Throws if
- * validation fails. This is the throwing twin of {@link validateSchema}.
- *
- * Use when you want fail-fast semantics at a trust boundary. For recoverable
- * validation (form input, external configs), prefer {@link validateSchema}.
- *
- * @throws {Error} When validation fails. The message lists all issues.
- */
-export declare function parseSchema<S>(schema: S, data: unknown): Infer<S>;
-export {};