upstash-lua 0.3.0

package/README.md

@@ -0,0 +1,319 @@
+![Hero](https://raw.githubusercontent.com/strandhvilliam/upstash-lua/main/assets/upstash-lua-hero.jpg)
+
+Type-safe Lua scripts for Upstash Redis with StandardSchemaV1 validation.
+
+## Features
+
+- **Full TypeScript inference** for keys, args, and return values
+- **Type-safe Lua templates** - Use `${KEYS.name}` and `${ARGV.name}` with autocomplete and compile-time errors
+- **Input validation** using StandardSchemaV1 schemas (Zod, Effect Schema, ArkType, etc.)
+- **Efficient execution** via EVALSHA with automatic NOSCRIPT fallback
+- **Universal runtime support** - Node.js 18+, Bun, Cloudflare Workers, Vercel Edge
+
+## Installation
+
+```bash
+bun add upstash-lua @upstash/redis zod
+# or
+npm install upstash-lua @upstash/redis zod
+```
+
+## Quick Start
+
+```typescript
+import { z } from "zod"
+import { defineScript, lua } from "upstash-lua"
+import { Redis } from "@upstash/redis"
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN,
+})
+
+// Define a rate limiter script with type-safe Lua template
+const rateLimit = defineScript({
+  name: "rateLimit",
+  keys: {
+    key: z.string(),
+  },
+  args: {
+    limit: z.number().int().positive().transform(String),
+    windowSeconds: z.number().int().positive().transform(String),
+  },
+  lua: ({ KEYS, ARGV }) => lua`
+    local current = redis.call("INCR", ${KEYS.key})
+    if current == 1 then
+      redis.call("EXPIRE", ${KEYS.key}, ${ARGV.windowSeconds})
+    end
+    local allowed = current <= tonumber(${ARGV.limit}) and 1 or 0
+    return { allowed, tonumber(${ARGV.limit}) - current }
+  `,
+  returns: z.tuple([z.number(), z.number()]).transform(([allowed, rem]) => ({
+    allowed: allowed === 1,
+    remaining: rem,
+  })),
+})
+
+// Execute with full type safety
+const result = await rateLimit.run(redis, {
+  keys: { key: "rl:user:123" },
+  args: { limit: 10, windowSeconds: 60 },
+})
+
+console.log(result.allowed)   // boolean
+console.log(result.remaining) // number
+```
+
+## API
+
+### `defineScript(options)`
+
+Creates a type-safe Lua script definition.
+
+#### Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Human-readable name (used in error messages) |
+| `lua` | `string \| LuaFunction` | Lua script source code (string) or type-safe template function |
+| `keys` | `Record<string, Schema>` | Key schemas - order determines KEYS[1], KEYS[2], etc. |
+| `args` | `Record<string, Schema>` | Arg schemas - order determines ARGV[1], ARGV[2], etc. |
+| `returns` | `Schema` | Optional return value schema |
+
+**Important:** Key/arg order is determined by object literal insertion order. Always define using object literal syntax in the intended order.
+
+#### Lua Property: String vs Function
+
+The `lua` property can be either a plain string or a function that returns a `lua` template:
+
+**String form** (manual KEYS/ARGV indexing):
+```typescript
+lua: `return redis.call("GET", KEYS[1])`
+```
+
+**Function form** (type-safe with autocomplete):
+```typescript
+lua: ({ KEYS, ARGV }) => lua`
+  return redis.call("GET", ${KEYS.userKey})
+`
+```
+
+The function form provides:
+- ✅ Autocomplete for `KEYS.*` and `ARGV.*` properties
+- ✅ Compile-time errors for invalid key/arg references
+- ✅ Automatic compilation of `${KEYS.name}` → `KEYS[n]` and `${ARGV.name}` → `ARGV[n]`
+
+#### Returns
+
+A `Script` object with:
+
+- `run(redis, input)` - Execute with full validation
+- `runRaw(redis, input)` - Execute without return validation
+- `name`, `lua`, `keyNames`, `argNames` - Metadata
+
+### Schema Requirements
+
+Keys and args must output strings (Redis only accepts strings). Use transforms:
+
+```typescript
+args: {
+  // Number input → string output
+  limit: z.number().transform(String),
+  
+  // Boolean input → "1" or "0" output
+  enabled: z.boolean().transform(b => b ? "1" : "0"),
+  
+  // String input → string output (no transform needed)
+  key: z.string(),
+}
+```
+
+## Examples
+
+### Type-Safe Lua Template
+
+Use the `lua` tagged template function for type-safe key and argument references:
+
+```typescript
+import { defineScript, lua } from "upstash-lua"
+import { z } from "zod"
+
+const getUser = defineScript({
+  name: "getUser",
+  keys: {
+    userKey: z.string(),
+  },
+  args: {
+    field: z.string(),
+  },
+  lua: ({ KEYS, ARGV }) => lua`
+    -- TypeScript autocomplete works here!
+    local key = ${KEYS.userKey}
+    local field = ${ARGV.field}
+    return redis.call("HGET", key, field)
+  `,
+  returns: z.string().nullable(),
+})
+
+// ${KEYS.userKey} automatically becomes KEYS[1]
+// ${ARGV.field} automatically becomes ARGV[1]
+```
+
+### Simple Script (No Keys/Args)
+
+```typescript
+const ping = defineScript({
+  name: "ping",
+  lua: 'return redis.call("PING")',
+  returns: z.string(),
+})
+
+const result = await ping.run(redis)
+// result: "PONG"
+```
+
+Or with the function form:
+
+```typescript
+const ping = defineScript({
+  name: "ping",
+  lua: () => lua`return redis.call("PING")`,
+  returns: z.string(),
+})
+```
+
+### Script Without Return Validation
+
+```typescript
+const getData = defineScript({
+  name: "getData",
+  lua: 'return redis.call("HGETALL", KEYS[1])',
+  keys: { key: z.string() },
+  // No returns schema - result is unknown
+})
+
+const result = await getData.run(redis, { keys: { key: "user:123" } })
+// result: unknown
+```
+
+### HGETALL with `hashResult()`
+
+Redis commands like `HGETALL` return flat arrays of alternating key-value pairs:
+`["field1", "value1", "field2", "value2"]`
+
+The `hashResult()` helper converts this to an object before validation, enabling you to use `z.object()`:
+
+```typescript
+import { z } from "zod"
+import { defineScript, hashResult } from "upstash-lua"
+
+const getUser = defineScript({
+  name: "getUser",
+  keys: { key: z.string() },
+  lua: 'return redis.call("HGETALL", KEYS[1])',
+  returns: hashResult(z.object({
+    name: z.string(),
+    email: z.string(),
+    age: z.coerce.number(),
+    is_admin: z.string().transform(v => v === "true"),
+  })),
+})
+
+const user = await getUser.run(redis, { keys: { key: "user:123" } })
+// user: { name: string, email: string, age: number, is_admin: boolean }
+```
+
+Works with all Zod object features:
+
+```typescript
+// Optional fields
+returns: hashResult(z.object({
+  name: z.string(),
+  email: z.string().optional(),
+}))
+
+// Partial objects
+returns: hashResult(z.object({
+  name: z.string(),
+  email: z.string(),
+}).partial())
+
+// Passthrough for extra fields
+returns: hashResult(z.object({
+  name: z.string(),
+}).passthrough())
+```
+
+### Effect Schema Example
+
+```typescript
+import { Schema } from "effect"
+import { defineScript, lua } from "upstash-lua"
+
+const incr = defineScript({
+  name: "incr",
+  keys: {
+    key: Schema.standardSchemaV1(Schema.String),
+  },
+  args: {
+    amount: Schema.standardSchemaV1(
+      Schema.Number.pipe(
+        Schema.transform(Schema.String, (n) => String(n), (s) => Number(s))
+      )
+    ),
+  },
+  lua: ({ KEYS, ARGV }) => lua`
+    return redis.call("INCRBY", ${KEYS.key}, ${ARGV.amount})
+  `,
+  returns: Schema.standardSchemaV1(Schema.Number),
+})
+```
+
+## Error Handling
+
+Errors are thrown as `Error` objects with descriptive messages when validation fails:
+
+```typescript
+try {
+  await script.run(redis, { args: { limit: -1 } })
+} catch (error) {
+  if (error instanceof Error) {
+    console.error(error.message)
+    // "[upstash-lua@0.2.0] Script \"rateLimit\" input validation failed at \"args.limit\": Number must be positive"
+  }
+}
+```
+
+Error messages include:
+- The library version
+- The script name
+- The validation path (for input errors)
+- The validation error messages
+
+## How It Works
+
+1. **Define** - Creates script with metadata and computed SHA1
+   - If `lua` is a function, it's called with typed `KEYS`/`ARGV` proxies
+   - The `lua` template is compiled: `${KEYS.name}` → `KEYS[n]`, `${ARGV.name}` → `ARGV[n]`
+2. **Validate** - Keys/args are validated against StandardSchemaV1 schemas
+3. **Transform** - Validated values are transformed (e.g., numbers → strings)
+4. **Execute** - Uses EVALSHA for efficiency, falls back to SCRIPT LOAD on NOSCRIPT
+5. **Parse** - Return value is validated/transformed if schema provided
+
+The library caches script loading per-client, so concurrent calls share a single SCRIPT LOAD.
+
+## Versioning
+
+```typescript
+import { VERSION } from "upstash-lua"
+console.log(`Using upstash-lua v${VERSION}`)
+```
+
+Errors include the version for debugging:
+```
+[upstash-lua@0.1.0] Script "rateLimit" input validation failed at "args.limit": ...
+```
+
+## License
+
+MIT

package/dist/define-script.d.ts

@@ -0,0 +1,250 @@
+import type { RedisLike } from "./redis-like.ts";
+import type { AnyStandardSchema, ScriptCallArgs, StdOutput, StringSchemaRecord } from "./types.ts";
+import { type CompiledLua, type TokenProxy } from "./lua-template.ts";
+/**
+ * Represents a defined Lua script with type-safe execution methods.
+ *
+ * The Script object is created by `defineScript()` and provides methods
+ * to execute the script with validated inputs and typed outputs.
+ *
+ * @typeParam K - The keys schema record
+ * @typeParam A - The args schema record
+ * @typeParam R - The return type after validation
+ *
+ * @example
+ * ```ts
+ * const myScript: Script<{ key: z.ZodString }, { limit: z.ZodNumber }, number> = defineScript({
+ *   name: "myScript",
+ *   lua: `return redis.call("INCR", KEYS[1])`,
+ *   keys: { key: z.string() },
+ *   args: { limit: z.number().transform(String) },
+ *   returns: z.number(),
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface Script<K extends StringSchemaRecord, A extends StringSchemaRecord, R> {
+    /**
+     * Human-readable name of the script.
+     * Used in error messages for debugging.
+     */
+    readonly name: string;
+    /**
+     * The Lua script source code.
+     */
+    readonly lua: string;
+    /**
+     * Ordered list of key names.
+     * The order matches KEYS[1], KEYS[2], etc. in the Lua script.
+     * Derived from `Object.keys(def.keys)` at definition time.
+     */
+    readonly keyNames: readonly Extract<keyof K, string>[];
+    /**
+     * Ordered list of argument names.
+     * The order matches ARGV[1], ARGV[2], etc. in the Lua script.
+     * Derived from `Object.keys(def.args)` at definition time.
+     */
+    readonly argNames: readonly Extract<keyof A, string>[];
+    /**
+     * Executes the script without validating the return value.
+     *
+     * Use this when you don't need return validation or want to handle
+     * the raw Redis response yourself.
+     *
+     * @param redis - The Redis client to execute on
+     * @param input - The keys and args (omit if both are empty)
+     * @returns Promise resolving to the raw Redis response
+     *
+     * @example
+     * ```ts
+     * const raw = await myScript.runRaw(redis, {
+     *   keys: { key: "test" },
+     *   args: { limit: 10 },
+     * })
+     * ```
+     *
+     * @since 0.1.0
+     */
+    runRaw(redis: RedisLike, ...input: ScriptCallArgs<K, A>): Promise<unknown>;
+    /**
+     * Executes the script with full input and return validation.
+     *
+     * This is the primary method for executing scripts. It:
+     * 1. Validates all keys and args against their schemas
+     * 2. Transforms validated values (e.g., numbers to strings)
+     * 3. Executes the script via EVALSHA (with NOSCRIPT fallback)
+     * 4. Validates and transforms the return value (if returns schema provided)
+     *
+     * @param redis - The Redis client to execute on
+     * @param input - The keys and args (omit if both are empty)
+     * @returns Promise resolving to the validated and transformed return value
+     * @throws {Error} When validation fails
+     *
+     * @example
+     * ```ts
+     * const result = await myScript.run(redis, {
+     *   keys: { key: "test" },
+     *   args: { limit: 10 },
+     * })
+     * ```
+     *
+     * @since 0.1.0
+     */
+    run(redis: RedisLike, ...input: ScriptCallArgs<K, A>): Promise<R>;
+}
+/**
+ * Function type for type-safe Lua script definition.
+ *
+ * Receives typed `KEYS` and `ARGV` proxy objects and returns a `CompiledLua`
+ * template created with the `lua` tagged template function.
+ *
+ * @typeParam K - The keys schema record
+ * @typeParam A - The args schema record
+ *
+ * @example
+ * ```ts
+ * lua: ({ KEYS, ARGV }) => lua`
+ *   local key = ${KEYS.userKey}
+ *   local limit = tonumber(${ARGV.limit})
+ *   return redis.call("GET", key)
+ * `
+ * ```
+ *
+ * @since 0.2.0
+ */
+export type LuaFunction<K extends StringSchemaRecord, A extends StringSchemaRecord> = (ctx: {
+    KEYS: TokenProxy<K>;
+    ARGV: TokenProxy<A>;
+}) => CompiledLua;
+/**
+ * Base definition for a Lua script.
+ *
+ * @typeParam K - The keys schema record
+ * @typeParam A - The args schema record
+ *
+ * @since 0.1.0
+ */
+export interface DefineScriptBase<K extends StringSchemaRecord, A extends StringSchemaRecord> {
+    /**
+     * Human-readable name for the script.
+     * Used in error messages for debugging.
+     */
+    name: string;
+    /**
+     * The Lua script source code.
+     *
+     * Can be either:
+     * - A plain string (for raw `.lua` files or manual scripts)
+     * - A function receiving typed `KEYS`/`ARGV` proxies and returning a `lua` template
+     *
+     * When using the function form, you get:
+     * - Autocomplete for `KEYS.*` and `ARGV.*`
+     * - Compile-time errors for invalid key/arg references
+     * - Automatic compilation of `${KEYS.name}` to `KEYS[n]`
+     *
+     * @example
+     * ```ts
+     * // String form (no type safety for KEYS/ARGV):
+     * lua: `return redis.call("GET", KEYS[1])`
+     *
+     * // Function form (type-safe):
+     * lua: ({ KEYS, ARGV }) => lua`
+     *   local key = ${KEYS.userKey}
+     *   return redis.call("GET", key)
+     * `
+     * ```
+     */
+    lua: string | LuaFunction<K, A>;
+    /**
+     * Record of key schemas.
+     *
+     * **Important:** The order of keys in this object determines the order
+     * they appear in KEYS[1], KEYS[2], etc. Define keys using object literal
+     * syntax in the intended order. Do not spread from unknown sources.
+     *
+     * Each schema must output a string (use `.transform(String)` if needed).
+     */
+    keys?: K;
+    /**
+     * Record of argument schemas.
+     *
+     * **Important:** The order of args in this object determines the order
+     * they appear in ARGV[1], ARGV[2], etc. Define args using object literal
+     * syntax in the intended order. Do not spread from unknown sources.
+     *
+     * Each schema must output a string (use `.transform(String)` if needed).
+     */
+    args?: A;
+}
+/**
+ * Defines a type-safe Lua script for execution on Upstash Redis.
+ *
+ * This function creates a Script object that:
+ * - Validates keys and args using StandardSchemaV1 schemas
+ * - Transforms values (e.g., numbers to strings for Redis)
+ * - Executes efficiently via EVALSHA with automatic NOSCRIPT fallback
+ * - Validates and transforms return values
+ *
+ * **Key ordering:** The order of keys/args in the definition object determines
+ * their order in KEYS[1], KEYS[2] and ARGV[1], ARGV[2], etc. Always define
+ * using object literal syntax in the intended order.
+ *
+ * @param def - Script definition with name, lua, keys, args, and optional returns
+ * @returns A Script object with `run()` and `runRaw()` methods
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod"
+ * import { defineScript } from "upstash-lua"
+ *
+ * const rateLimit = defineScript({
+ *   name: "rateLimit",
+ *   lua: `
+ *     local current = redis.call("INCR", KEYS[1])
+ *     if current == 1 then
+ *       redis.call("EXPIRE", KEYS[1], ARGV[2])
+ *     end
+ *     local allowed = current <= tonumber(ARGV[1]) and 1 or 0
+ *     return { allowed, tonumber(ARGV[1]) - current }
+ *   `,
+ *   keys: {
+ *     key: z.string(),
+ *   },
+ *   args: {
+ *     limit: z.number().int().positive().transform(String),
+ *     windowSeconds: z.number().int().positive().transform(String),
+ *   },
+ *   returns: z.tuple([z.number(), z.number()]).transform(([allowed, rem]) => ({
+ *     allowed: allowed === 1,
+ *     remaining: rem,
+ *   })),
+ * })
+ *
+ * const result = await rateLimit.run(redis, {
+ *   keys: { key: "rl:user:123" },
+ *   args: { limit: 10, windowSeconds: 60 },
+ * })
+ * // result: { allowed: boolean, remaining: number }
+ * ```
+ *
+ * @see https://github.com/your-org/upstash-lua for full documentation
+ * @since 0.1.0
+ */
+export declare function defineScript<const K extends StringSchemaRecord, const A extends StringSchemaRecord, const Ret extends AnyStandardSchema>(def: DefineScriptBase<K, A> & {
+    returns: Ret;
+}): Script<K, A, StdOutput<Ret>>;
+/**
+ * Defines a Lua script without return validation.
+ *
+ * When no `returns` schema is provided, `run()` returns `unknown`.
+ *
+ * @param def - Script definition with name, lua, keys, and args
+ * @returns A Script object with `run()` returning `unknown`
+ *
+ * @since 0.1.0
+ */
+export declare function defineScript<const K extends StringSchemaRecord, const A extends StringSchemaRecord>(def: DefineScriptBase<K, A> & {
+    returns?: undefined;
+}): Script<K, A, unknown>;
+//# sourceMappingURL=define-script.d.ts.map

package/dist/define-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-script.d.ts","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EAEd,SAAS,EACT,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAInB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EAIhB,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,kBAAkB,EAAE,CAAC,SAAS,kBAAkB,EAAE,CAAC;IACnF;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,CAAA;IAEtD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,CAAA;IAEtD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE1E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CAClE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,kBAAkB,EAAE,CAAC,SAAS,kBAAkB,IAAI,CAAC,GAAG,EAAE;IAC1F,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;IACnB,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CACpB,KAAK,WAAW,CAAA;AAEjB;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,kBAAkB,EAAE,CAAC,SAAS,kBAAkB;IAC1F;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAE/B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,CAAC,CAAA;IAER;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,CAAC,CAAA;CACT;AAkGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,YAAY,CAC1B,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAClC,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAClC,KAAK,CAAC,GAAG,SAAS,iBAAiB,EACnC,GAAG,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,OAAO,EAAE,GAAG,CAAA;CAAE,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;AAE/E;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAClC,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAClC,GAAG,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAA"}

package/dist/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Represents a validation issue from a StandardSchemaV1 schema.
+ * This is a simplified representation that works across different schema libraries.
+ *
+ * @since 0.1.0
+ */
+export interface ValidationIssue {
+    /** Human-readable error message */
+    readonly message: string;
+    /** Path to the invalid value within the input */
+    readonly path?: ReadonlyArray<PropertyKey>;
+}
+/**
+ * Error thrown when script input validation fails.
+ *
+ * This error is thrown when keys or args fail to validate against their
+ * respective StandardSchemaV1 schemas before the script is executed.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await myScript.run(redis, { keys: { key: "" }, args: { limit: -1 } })
+ * } catch (error) {
+ *   if (error instanceof ScriptInputError) {
+ *     console.error(`Script: ${error.scriptName}`)
+ *     console.error(`Field: ${error.path}`)  // e.g., "args.limit"
+ *     console.error(`Issues:`, error.issues)
+ *   }
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class ScriptInputError extends Error {
+    /**
+     * The name of the script that failed validation.
+     * Matches the `name` property in the script definition.
+     */
+    readonly scriptName: string;
+    /**
+     * The path to the invalid field.
+     * Format: `"keys.<fieldName>"` or `"args.<fieldName>"`
+     *
+     * @example "args.limit", "keys.userId"
+     */
+    readonly path: string;
+    /**
+     * Array of validation issues from the schema library.
+     * Each issue contains at least a `message` property.
+     */
+    readonly issues: readonly ValidationIssue[];
+    /**
+     * Creates a new ScriptInputError.
+     *
+     * @param scriptName - Name of the script that failed validation
+     * @param path - Path to the invalid field (e.g., "args.limit")
+     * @param issues - Array of validation issues from the schema
+     */
+    constructor(scriptName: string, path: string, issues: readonly ValidationIssue[]);
+}
+/**
+ * Error thrown when script return value validation fails.
+ *
+ * This error is thrown when the Redis response fails to validate against
+ * the `returns` StandardSchemaV1 schema after script execution.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await myScript.run(redis, { keys: { key: "test" } })
+ * } catch (error) {
+ *   if (error instanceof ScriptReturnError) {
+ *     console.error(`Script: ${error.scriptName}`)
+ *     console.error(`Raw response:`, error.raw)
+ *     console.error(`Issues:`, error.issues)
+ *   }
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class ScriptReturnError extends Error {
+    /**
+     * The name of the script whose return validation failed.
+     * Matches the `name` property in the script definition.
+     */
+    readonly scriptName: string;
+    /**
+     * Array of validation issues from the schema library.
+     * Each issue contains at least a `message` property.
+     */
+    readonly issues: readonly ValidationIssue[];
+    /**
+     * The raw value returned from Redis before validation.
+     * Useful for debugging schema mismatches.
+     */
+    readonly raw: unknown;
+    /**
+     * Creates a new ScriptReturnError.
+     *
+     * @param scriptName - Name of the script that failed validation
+     * @param issues - Array of validation issues from the schema
+     * @param raw - The raw Redis response that failed validation
+     */
+    constructor(scriptName: string, issues: readonly ValidationIssue[], raw: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;IAE3C;;;;;;OAMG;gBAED,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,eAAe,EAAE;CAiBrC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;IAE3C;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IAErB;;;;;;OAMG;gBAED,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,GAAG,EAAE,OAAO;CAiBf"}