upstash-lua 0.3.0

package/dist/redis-like.d.ts

@@ -0,0 +1,90 @@
+/**
+ * A minimal interface for Upstash Redis that support Lua script execution.
+ *
+ * This interface is designed to be compatible with Upstash Redis and possibly other
+ * Redis clients.
+ *
+ * **Compatibility:**
+ * - Upstash Redis (`@upstash/redis`) - Fully compatible
+ *
+ * @example
+ * ```ts
+ * import { Redis } from "@upstash/redis"
+ *
+ * const redis = new Redis({
+ *   url: process.env.UPSTASH_REDIS_REST_URL,
+ *   token: process.env.UPSTASH_REDIS_REST_TOKEN,
+ * })
+ *
+ * // redis is compatible with RedisLike
+ * await myScript.run(redis, { keys: { key: "test" } })
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface RedisLike {
+    /**
+     * Executes a Lua script directly.
+     *
+     * This method sends the full script source to Redis for execution.
+     * It is less efficient than `evalsha` for repeated executions of the
+     * same script, as the script must be parsed each time.
+     *
+     * @param script - The Lua script source code
+     * @param keys - Array of Redis keys used by the script (accessed as KEYS[1], KEYS[2], etc.)
+     * @param args - Array of additional arguments (accessed as ARGV[1], ARGV[2], etc.)
+     * @returns Promise resolving to the script's return value
+     *
+     * @example
+     * ```ts
+     * const result = await redis.eval(
+     *   'return redis.call("GET", KEYS[1])',
+     *   ["mykey"],
+     *   []
+     * )
+     * ```
+     */
+    eval(script: string, keys: string[], args: string[]): Promise<unknown>;
+    /**
+     * Executes a cached Lua script by its SHA1 hash.
+     *
+     * This is the preferred method for executing scripts, as it avoids
+     * sending the full script source over the network. The script must
+     * have been previously loaded using `scriptLoad`.
+     *
+     * If the script is not cached on the server, Redis returns a NOSCRIPT
+     * error. The library handles this automatically by loading the script
+     * and retrying.
+     *
+     * @param sha1 - The SHA1 hash of the script (40 hexadecimal characters)
+     * @param keys - Array of Redis keys used by the script
+     * @param args - Array of additional arguments
+     * @returns Promise resolving to the script's return value
+     * @throws Error with message containing "NOSCRIPT" if script is not cached
+     *
+     * @example
+     * ```ts
+     * const sha = await redis.scriptLoad('return "hello"')
+     * const result = await redis.evalsha(sha, [], [])
+     * ```
+     */
+    evalsha(sha1: string, keys: string[], args: string[]): Promise<unknown>;
+    /**
+     * Loads a Lua script into the Redis script cache.
+     *
+     * The script is cached on the server and can be executed later using
+     * `evalsha` with the returned SHA1 hash. This avoids sending the full
+     * script source for each execution.
+     *
+     * @param script - The Lua script source code to cache
+     * @returns Promise resolving to the SHA1 hash of the script
+     *
+     * @example
+     * ```ts
+     * const sha = await redis.scriptLoad('return redis.call("PING")')
+     * console.log(sha) // "e.g., a42059b356c875f0717db19a51f6aaa9161e77a2"
+     * ```
+     */
+    scriptLoad(script: string): Promise<string>;
+}
+//# sourceMappingURL=redis-like.d.ts.map

package/dist/redis-like.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-like.d.ts","sourceRoot":"","sources":["../src/redis-like.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvE;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5C"}

package/dist/sha1.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Computes the SHA1 hash of a string and returns it as a hexadecimal string.
+ *
+ * This implementation uses the WebCrypto API, which is available in:
+ * - Node.js 18+ (via `globalThis.crypto.subtle`)
+ * - Bun (full WebCrypto support)
+ * - Cloudflare Workers
+ * - Vercel Edge Runtime
+ * - Deno
+ *
+ * The SHA1 hash is used by Redis to identify cached Lua scripts for
+ * efficient execution via EVALSHA.
+ *
+ * @param text - The string to hash (typically a Lua script)
+ * @returns Promise resolving to the 40-character lowercase hexadecimal SHA1 hash
+ *
+ * @example
+ * ```ts
+ * const hash = await sha1Hex('return redis.call("PING")')
+ * console.log(hash) // "e.g., a42059b356c875f0717db19a51f6aaa9161e77a2"
+ * ```
+ *
+ * @throws {Error} If WebCrypto is not available in the runtime
+ *
+ * @since 0.1.0
+ */
+export declare function sha1Hex(text: string): Promise<string>;
+//# sourceMappingURL=sha1.d.ts.map

package/dist/sha1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha1.d.ts","sourceRoot":"","sources":["../src/sha1.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAa3D"}

package/dist/standard-schema.d.ts

@@ -0,0 +1,112 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * 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>;
+}
+/**
+ * Result of a successful validation.
+ *
+ * @since 0.1.0
+ */
+export interface ValidationSuccess<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/**
+ * Result of a failed validation.
+ *
+ * @since 0.1.0
+ */
+export interface ValidationFailure {
+    readonly ok: false;
+    readonly issues: readonly ValidationIssue[];
+}
+/**
+ * Result of validating a value against a StandardSchemaV1 schema.
+ *
+ * @since 0.1.0
+ */
+export type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+/**
+ * Validates a value against a StandardSchemaV1 schema.
+ *
+ * This function handles both synchronous and asynchronous validation,
+ * as StandardSchemaV1 allows either. It returns a discriminated union
+ * for easy handling of success/failure cases.
+ *
+ * @param schema - The StandardSchemaV1 schema to validate against
+ * @param value - The value to validate
+ * @returns A promise resolving to either `{ ok: true, value }` or `{ ok: false, issues }`
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod"
+ *
+ * const result = await validateStandard(z.string(), "hello")
+ * if (result.ok) {
+ *   console.log(result.value) // "hello"
+ * } else {
+ *   console.error(result.issues)
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare function validateStandard<I, O>(schema: StandardSchemaV1<I, O>, value: I): Promise<ValidationResult<O>>;
+/**
+ * Context for parsing operations, used to generate meaningful error messages.
+ *
+ * @since 0.1.0
+ */
+export interface ParseContext {
+    /** Name of the script being executed */
+    readonly scriptName: string;
+    /** Path to the field being validated (e.g., "keys.userId" or "args.limit") */
+    readonly path: string;
+    /** Type of value being parsed: "input" for keys/args, "return" for script response */
+    readonly type: "input" | "return";
+    /** Raw value (only for return validation, used in error reporting) */
+    readonly raw?: unknown;
+}
+/**
+ * Validates a value and throws a descriptive error on failure.
+ *
+ * This is a convenience wrapper around `validateStandard` that throws
+ * appropriate error types based on the context.
+ *
+ * @param schema - The StandardSchemaV1 schema to validate against
+ * @param value - The value to validate
+ * @param context - Context for error messages
+ * @returns The validated and potentially transformed value
+ * @throws {Error} When validation fails
+ *
+ * @example
+ * ```ts
+ * // For input validation:
+ * const validated = await parseStandard(schema, input, {
+ *   scriptName: "myScript",
+ *   path: "args.limit",
+ *   type: "input"
+ * })
+ *
+ * // For return validation:
+ * const result = await parseStandard(schema, rawResult, {
+ *   scriptName: "myScript",
+ *   path: "return",
+ *   type: "return",
+ *   raw: rawResult
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare function parseStandard<I, O>(schema: StandardSchemaV1<I, O>, value: I, context: ParseContext): Promise<O>;
+//# sourceMappingURL=standard-schema.d.ts.map

package/dist/standard-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-schema.d.ts","sourceRoot":"","sources":["../src/standard-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAI7D;;;;;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;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;CAC5C;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAA;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACzC,MAAM,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC9B,KAAK,EAAE,CAAC,GACP,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAsB9B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAA;IACjC,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,CAAC,EACtC,MAAM,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC9B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,CAAC,CAAC,CAkBZ"}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * Represents any StandardSchemaV1 schema with arbitrary input and output types.
+ *
+ * @since 0.1.0
+ */
+export type AnyStandardSchema = StandardSchemaV1<unknown, unknown>;
+/**
+ * Extracts the input type from a StandardSchemaV1 schema.
+ *
+ * @typeParam S - The StandardSchemaV1 schema type
+ * @returns The input type that the schema accepts for validation
+ *
+ * @example
+ * ```ts
+ * // With Zod:
+ * type Input = StdInput<typeof z.string()> // string
+ * type Input2 = StdInput<typeof z.number().transform(String)> // number
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type StdInput<S extends AnyStandardSchema> = S extends StandardSchemaV1<infer I, unknown> ? I : never;
+/**
+ * Extracts the output type from a StandardSchemaV1 schema.
+ *
+ * @typeParam S - The StandardSchemaV1 schema type
+ * @returns The output type after validation and transformation
+ *
+ * @example
+ * ```ts
+ * // With Zod:
+ * type Output = StdOutput<typeof z.string()> // string
+ * type Output2 = StdOutput<typeof z.number().transform(String)> // string
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type StdOutput<S extends AnyStandardSchema> = S extends StandardSchemaV1<unknown, infer O> ? O : never;
+/**
+ * A StandardSchemaV1 schema that outputs a string.
+ * Used for keys and args which must be strings when sent to Redis.
+ *
+ * @since 0.1.0
+ */
+export type StringOutSchema = StandardSchemaV1<unknown, string>;
+/**
+ * A record of named schemas that all output strings.
+ * Used for defining keys and args in script definitions.
+ *
+ * @since 0.1.0
+ */
+export type StringSchemaRecord = Record<string, StringOutSchema>;
+/**
+ * Maps a record of schemas to their input types.
+ *
+ * @typeParam T - Record of StandardSchemaV1 schemas
+ * @returns Object type with same keys but input types as values
+ *
+ * @example
+ * ```ts
+ * type Inputs = InputsOf<{
+ *   key: typeof z.string(),
+ *   limit: typeof z.number().transform(String)
+ * }>
+ * // { key: string; limit: number }
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type InputsOf<T extends Record<string, AnyStandardSchema>> = {
+    [K in keyof T]: StdInput<T[K]>;
+};
+/**
+ * Maps a record of schemas to their output types.
+ *
+ * @typeParam T - Record of StandardSchemaV1 schemas
+ * @returns Object type with same keys but output types as values
+ *
+ * @since 0.1.0
+ */
+export type OutputsOf<T extends Record<string, AnyStandardSchema>> = {
+    [K in keyof T]: StdOutput<T[K]>;
+};
+/**
+ * Computes the input payload shape required by `run()`, depending on whether
+ * keys and/or args are defined (non-empty records).
+ *
+ * - If both are empty: `{}`
+ * - If only keys defined: `{ keys: ... }`
+ * - If only args defined: `{ args: ... }`
+ * - If both defined: `{ keys: ..., args: ... }`
+ *
+ * @typeParam K - The keys schema record
+ * @typeParam A - The args schema record
+ *
+ * @since 0.1.0
+ */
+export type ScriptCallInput<K extends StringSchemaRecord, A extends StringSchemaRecord> = (keyof K extends never ? object : {
+    keys: InputsOf<K>;
+}) & (keyof A extends never ? object : {
+    args: InputsOf<A>;
+});
+/**
+ * Rest-parameter tuple type for `run()` method.
+ *
+ * - When no keys and no args: `[]` (no second argument)
+ * - Otherwise: `[input: ScriptCallInput<K, A>]`
+ *
+ * This enables clean call signatures:
+ * - `run(redis)` when keys and args are both empty
+ * - `run(redis, { keys, args })` otherwise
+ *
+ * @typeParam K - The keys schema record
+ * @typeParam A - The args schema record
+ *
+ * @since 0.1.0
+ */
+export type ScriptCallArgs<K extends StringSchemaRecord, A extends StringSchemaRecord> = keyof ScriptCallInput<K, A> extends never ? [] : [input: ScriptCallInput<K, A>];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE7D;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAElE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,iBAAiB,IAAI,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GAC5F,CAAC,GACD,KAAK,CAAA;AAET;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,iBAAiB,IAAI,CAAC,SAAS,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAC7F,CAAC,GACD,KAAK,CAAA;AAET;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;AAEhE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,IAAI;KACjE,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,IAAI;KAClE,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAChC,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,CACzB,CAAC,SAAS,kBAAkB,EAC5B,CAAC,SAAS,kBAAkB,IAC1B,CAAC,MAAM,CAAC,SAAS,KAAK,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,GAC1D,CAAC,MAAM,CAAC,SAAS,KAAK,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,CAAA;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,CACxB,CAAC,SAAS,kBAAkB,EAC5B,CAAC,SAAS,kBAAkB,IAC1B,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,GAAG,EAAE,GAAG,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA"}

package/dist/version.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The current version of the upstash-lua library.
+ * Follows semantic versioning (semver).
+ *
+ * This constant is useful for:
+ * - Debugging: knowing which version is in use
+ * - Logging: including version in log messages
+ * - Compatibility checks: comparing versions programmatically
+ *
+ * @example
+ * ```ts
+ * import { VERSION } from "upstash-lua"
+ * console.log(`Using upstash-lua v${VERSION}`)
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const VERSION: "0.3.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO,EAAG,OAAgB,CAAA"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "upstash-lua",
+  "version": "0.3.0",
+  "description": "Type-safe Lua scripts for Upstash with StandardSchema validation",
+  "author": "Villiam Strandh",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "upstash",
+    "redis",
+    "lua",
+    "scripts",
+    "typescript",
+    "zod",
+    "validation",
+    "standard-schema"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "zod": "^4.3.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  }
+}