upstash-lua 0.3.0

package/dist/eval-with-cache.d.ts

@@ -0,0 +1,73 @@
+import type { RedisLike } from "./redis-like.ts";
+/**
+ * Checks if an error is a Redis NOSCRIPT error.
+ *
+ * NOSCRIPT errors occur when attempting to execute a script via EVALSHA
+ * but the script has not been loaded into the Redis script cache.
+ *
+ * @param error - The error to check
+ * @returns True if the error indicates the script is not cached
+ *
+ * @since 0.1.0
+ */
+export declare function isNoScriptError(error: unknown): boolean;
+/**
+ * Ensures a script is loaded on the Redis server.
+ *
+ * This function handles concurrent requests - if multiple calls arrive
+ * for the same script before it's loaded, they all share the same
+ * SCRIPT LOAD operation.
+ *
+ * @param redis - The Redis client
+ * @param sha - The expected SHA1 hash of the script
+ * @param script - The Lua script source code
+ * @returns Promise that resolves when the script is loaded
+ *
+ * @since 0.1.0
+ */
+export declare function ensureLoaded(redis: RedisLike, sha: string, script: string): Promise<void>;
+/**
+ * Options for executing a script with caching.
+ *
+ * @since 0.1.0
+ */
+export interface EvalWithCacheOptions {
+    /** The Lua script source code */
+    readonly script: string;
+    /** The SHA1 hash of the script */
+    readonly sha: string;
+    /** Array of Redis keys (KEYS[1], KEYS[2], etc.) */
+    readonly keys: string[];
+    /** Array of arguments (ARGV[1], ARGV[2], etc.) */
+    readonly args: string[];
+}
+/**
+ * Executes a Lua script using EVALSHA with automatic NOSCRIPT fallback.
+ *
+ * This function implements the optimal execution strategy:
+ * 1. Try EVALSHA first (most efficient, assumes script is cached)
+ * 2. On NOSCRIPT error, load the script via SCRIPT LOAD
+ * 3. Retry EVALSHA
+ *
+ * The script loading is cached per-client, so subsequent calls for the
+ * same script won't trigger additional SCRIPT LOAD operations. Concurrent
+ * calls for the same script share a single SCRIPT LOAD.
+ *
+ * @param redis - The Redis client to execute on
+ * @param options - Script and parameters
+ * @returns Promise resolving to the script's return value
+ *
+ * @example
+ * ```ts
+ * const result = await evalWithCache(redis, {
+ *   script: 'return redis.call("GET", KEYS[1])',
+ *   sha: "abc123...",
+ *   keys: ["mykey"],
+ *   args: [],
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare function evalWithCache(redis: RedisLike, options: EvalWithCacheOptions): Promise<unknown>;
+//# sourceMappingURL=eval-with-cache.d.ts.map

package/dist/eval-with-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-with-cache.d.ts","sourceRoot":"","sources":["../src/eval-with-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAahD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQvD;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB/F;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,kCAAkC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;IACvB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAalB"}

package/dist/hash-result.d.ts

@@ -0,0 +1,48 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { AnyStandardSchema, StdOutput } from "./types.ts";
+/**
+ * Wraps a StandardSchemaV1 object schema to accept HGETALL-style array input.
+ *
+ * Redis commands like `HGETALL` return flat arrays of alternating key-value pairs:
+ * `["field1", "value1", "field2", "value2"]`
+ *
+ * This helper converts that format to an object before validating with your schema,
+ * enabling a much cleaner DX:
+ *
+ * @typeParam S - The inner schema type (must accept object input)
+ * @param schema - A StandardSchemaV1 schema that validates objects
+ * @returns A new schema that accepts `unknown[]` and outputs the validated type
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod"
+ * import { defineScript, hashResult } from "upstash-lua"
+ *
+ * const getUser = defineScript({
+ *   name: "getUser",
+ *   lua: `return redis.call("HGETALL", KEYS[1])`,
+ *   keys: { key: z.string() },
+ *   returns: hashResult(z.object({
+ *     name: z.string(),
+ *     email: z.string(),
+ *     age: z.coerce.number(),
+ *   })),
+ * })
+ *
+ * // Result is typed as { name: string, email: string, age: number }
+ * const user = await getUser.run(redis, { keys: { key: "user:123" } })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Works with partial/optional fields too
+ * returns: hashResult(z.object({
+ *   name: z.string(),
+ *   email: z.string().optional(),
+ * }).partial())
+ * ```
+ *
+ * @since 0.3.0
+ */
+export declare function hashResult<S extends AnyStandardSchema>(schema: S): StandardSchemaV1<unknown[], StdOutput<S>>;
+//# sourceMappingURL=hash-result.d.ts.map

package/dist/hash-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-result.d.ts","sourceRoot":"","sources":["../src/hash-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AA6C9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,iBAAiB,EACpD,MAAM,EAAE,CAAC,GACR,gBAAgB,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAiC3C"}

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * upstash-lua - Type-safe Lua scripts for Upstash Redis
+ *
+ * This library provides a `defineScript()` function for creating type-safe
+ * Lua scripts with StandardSchemaV1 validation (Zod, Effect Schema, ArkType, etc.).
+ *
+ * Features:
+ * - Full TypeScript inference for keys, args, and return values
+ * - Input validation and transformation using StandardSchemaV1 schemas
+ * - Efficient EVALSHA execution with automatic NOSCRIPT fallback
+ * - Universal runtime support (Node.js 18+, Bun, Edge runtimes)
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod"
+ * import { defineScript } from "upstash-lua"
+ * import { Redis } from "@upstash/redis"
+ *
+ * const redis = new Redis({ url: "...", token: "..." })
+ *
+ * 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
+ *     return { current <= tonumber(ARGV[1]) and 1 or 0, 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 }
+ * ```
+ *
+ * @packageDocumentation
+ * @module upstash-lua
+ * @since 0.1.0
+ */
+export { VERSION } from "./version.ts";
+export { defineScript } from "./define-script.ts";
+export type { Script, DefineScriptBase, LuaFunction } from "./define-script.ts";
+export { lua } from "./lua-template.ts";
+export type { CompiledLua, LuaToken, TokenProxy } from "./lua-template.ts";
+export type { RedisLike } from "./redis-like.ts";
+export { hashResult } from "./hash-result.ts";
+export type { AnyStandardSchema, StdInput, StdOutput, StringOutSchema, StringSchemaRecord, InputsOf, OutputsOf, ScriptCallInput, ScriptCallArgs, } from "./types.ts";
+export { validateStandard, parseStandard, } from "./standard-schema.ts";
+export type { ValidationSuccess, ValidationFailure, ValidationResult, ParseContext, } from "./standard-schema.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAG/E,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AACvC,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAG1E,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,SAAS,EACT,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,gBAAgB,EAChB,aAAa,GACd,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,GACb,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1,304 @@
+// src/version.ts
+var VERSION = "0.3.0";
+// src/standard-schema.ts
+async function validateStandard(schema, value) {
+  const result = schema["~standard"].validate(value);
+  const resolved = result instanceof Promise ? await result : result;
+  if ("issues" in resolved && resolved.issues) {
+    return {
+      ok: false,
+      issues: resolved.issues.map((issue) => ({
+        message: issue.message,
+        path: issue.path?.map((p) => typeof p === "object" && p !== null && ("key" in p) ? p.key : p)
+      }))
+    };
+  }
+  return {
+    ok: true,
+    value: resolved.value
+  };
+}
+async function parseStandard(schema, value, context) {
+  const result = await validateStandard(schema, value);
+  if (!result.ok) {
+    if (context.type === "input") {
+      const issueMessages = result.issues.map((i) => i.message).join(", ");
+      throw new Error(`[upstash-lua@${VERSION}] Script "${context.scriptName}" input validation failed at "${context.path}": ${issueMessages}`);
+    } else {
+      const issueMessages = result.issues.map((i) => i.message).join(", ");
+      throw new Error(`[upstash-lua@${VERSION}] Script "${context.scriptName}" return validation failed: ${issueMessages}`);
+    }
+  }
+  return result.value;
+}
+
+// src/eval-with-cache.ts
+var loadCache = new WeakMap;
+function isNoScriptError(error) {
+  if (error instanceof Error) {
+    return error.message.toUpperCase().includes("NOSCRIPT");
+  }
+  if (typeof error === "string") {
+    return error.toUpperCase().includes("NOSCRIPT");
+  }
+  return false;
+}
+function getClientCache(redis) {
+  let cache = loadCache.get(redis);
+  if (!cache) {
+    cache = new Map;
+    loadCache.set(redis, cache);
+  }
+  return cache;
+}
+async function ensureLoaded(redis, sha, script) {
+  const cache = getClientCache(redis);
+  const existing = cache.get(sha);
+  if (existing) {
+    return existing;
+  }
+  const loadPromise = (async () => {
+    await redis.scriptLoad(script);
+  })();
+  cache.set(sha, loadPromise);
+  try {
+    await loadPromise;
+  } catch (error) {
+    cache.delete(sha);
+    throw error;
+  }
+}
+async function evalWithCache(redis, options) {
+  const { script, sha, keys, args } = options;
+  try {
+    return await redis.evalsha(sha, keys, args);
+  } catch (error) {
+    if (!isNoScriptError(error)) {
+      throw error;
+    }
+    await ensureLoaded(redis, sha, script);
+    return await redis.evalsha(sha, keys, args);
+  }
+}
+
+// src/sha1.ts
+async function sha1Hex(text) {
+  if (typeof crypto === "undefined" || !crypto.subtle) {
+    throw new Error("[upstash-lua] WebCrypto (crypto.subtle) is not available. " + "This library requires Node.js 18+, Bun, or an Edge runtime.");
+  }
+  const encoder = new TextEncoder;
+  const data = encoder.encode(text);
+  const hashBuffer = await crypto.subtle.digest("SHA-1", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/lua-template.ts
+var LUA_TOKEN = Symbol("LUA_TOKEN");
+function isLuaToken(value) {
+  return typeof value === "object" && value !== null && LUA_TOKEN in value && value[LUA_TOKEN] === true;
+}
+function isCompiledLua(value) {
+  return typeof value === "object" && value !== null && LUA_TOKEN in value && value[LUA_TOKEN] === "compiled";
+}
+function createTokenProxy(kind) {
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (typeof prop !== "string") {
+        throw new TypeError(`[upstash-lua] ${kind.toUpperCase()}S proxy only accepts string keys`);
+      }
+      return {
+        [LUA_TOKEN]: true,
+        kind,
+        name: prop
+      };
+    }
+  });
+}
+function lua(strings, ...tokens) {
+  for (let i = 0;i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!isLuaToken(token)) {
+      throw new TypeError(`[upstash-lua] lua template only accepts KEYS.* or ARGV.* interpolations. ` + `Got ${typeof token} at position ${i + 1}.`);
+    }
+  }
+  return {
+    [LUA_TOKEN]: "compiled",
+    strings,
+    tokens
+  };
+}
+function compileLua(compiled, keyNames, argNames) {
+  const { strings, tokens } = compiled;
+  const keyIndexMap = new Map;
+  for (let i = 0;i < keyNames.length; i++) {
+    keyIndexMap.set(keyNames[i], i + 1);
+  }
+  const argIndexMap = new Map;
+  for (let i = 0;i < argNames.length; i++) {
+    argIndexMap.set(argNames[i], i + 1);
+  }
+  let result = strings[0] ?? "";
+  for (let i = 0;i < tokens.length; i++) {
+    const token = tokens[i];
+    let replacement;
+    if (token.kind === "key") {
+      const index = keyIndexMap.get(token.name);
+      if (index === undefined) {
+        throw new Error(`[upstash-lua] Unknown key "${token.name}" in lua template. ` + `Available keys: ${keyNames.length > 0 ? keyNames.join(", ") : "(none)"}`);
+      }
+      replacement = `KEYS[${index}]`;
+    } else {
+      const index = argIndexMap.get(token.name);
+      if (index === undefined) {
+        throw new Error(`[upstash-lua] Unknown arg "${token.name}" in lua template. ` + `Available args: ${argNames.length > 0 ? argNames.join(", ") : "(none)"}`);
+      }
+      replacement = `ARGV[${index}]`;
+    }
+    result += replacement + (strings[i + 1] ?? "");
+  }
+  return result;
+}
+
+// src/define-script.ts
+async function validateAndCollect(scriptName, keySchemas, argSchemas, keyNames, argNames, input) {
+  const keysArray = [];
+  const argsArray = [];
+  for (const keyName of keyNames) {
+    const schema = keySchemas[keyName];
+    const value = input.keys?.[keyName];
+    const validated = await parseStandard(schema, value, {
+      scriptName,
+      path: `keys.${keyName}`,
+      type: "input"
+    });
+    if (typeof validated !== "string") {
+      throw new TypeError(`[upstash-lua] Key "${keyName}" schema must output a string, got ${typeof validated}`);
+    }
+    keysArray.push(validated);
+  }
+  for (const argName of argNames) {
+    const schema = argSchemas[argName];
+    const value = input.args?.[argName];
+    const validated = await parseStandard(schema, value, {
+      scriptName,
+      path: `args.${argName}`,
+      type: "input"
+    });
+    if (typeof validated !== "string") {
+      throw new TypeError(`[upstash-lua] Arg "${argName}" schema must output a string, got ${typeof validated}`);
+    }
+    argsArray.push(validated);
+  }
+  return { keys: keysArray, args: argsArray };
+}
+function resolveLua(luaInput, keyNames, argNames) {
+  if (typeof luaInput === "string") {
+    return luaInput;
+  }
+  const KEYS = createTokenProxy("key");
+  const ARGV = createTokenProxy("arg");
+  const compiled = luaInput({ KEYS, ARGV });
+  if (!isCompiledLua(compiled)) {
+    throw new TypeError(`[upstash-lua] lua function must return a lua\`...\` template. ` + `Got ${typeof compiled}. Did you forget to use the lua tagged template?`);
+  }
+  return compileLua(compiled, keyNames, argNames);
+}
+function defineScript(def) {
+  const { name, lua: luaInput, keys: keySchemas = {}, args: argSchemas = {}, returns } = def;
+  const keyNames = Object.keys(keySchemas);
+  const argNames = Object.keys(argSchemas);
+  const lua2 = resolveLua(luaInput, keyNames, argNames);
+  let cachedSha;
+  async function getSha() {
+    if (cachedSha === undefined) {
+      cachedSha = await sha1Hex(lua2);
+    }
+    return cachedSha;
+  }
+  async function execute(redis, input) {
+    const { keys, args } = await validateAndCollect(name, keySchemas, argSchemas, keyNames, argNames, input);
+    const sha = await getSha();
+    return evalWithCache(redis, {
+      script: lua2,
+      sha,
+      keys,
+      args
+    });
+  }
+  return {
+    name,
+    lua: lua2,
+    keyNames,
+    argNames,
+    async runRaw(redis, ...inputArgs) {
+      const input = inputArgs[0] ?? {};
+      return execute(redis, input);
+    },
+    async run(redis, ...inputArgs) {
+      const input = inputArgs[0] ?? {};
+      const raw = await execute(redis, input);
+      if (!returns) {
+        return raw;
+      }
+      return parseStandard(returns, raw, {
+        scriptName: name,
+        path: "return",
+        type: "return",
+        raw
+      });
+    }
+  };
+}
+// src/hash-result.ts
+function pairsToObject(arr) {
+  if (!Array.isArray(arr)) {
+    throw new Error(`Expected array of key-value pairs, got ${typeof arr}`);
+  }
+  if (arr.length % 2 !== 0) {
+    throw new Error(`Expected even number of elements (key-value pairs), got ${arr.length}`);
+  }
+  const result = {};
+  for (let i = 0;i < arr.length; i += 2) {
+    const key = arr[i];
+    const value = arr[i + 1];
+    if (typeof key !== "string") {
+      throw new Error(`Expected string key at index ${i}, got ${typeof key}`);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function hashResult(schema) {
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "upstash-lua",
+      validate(value) {
+        let obj;
+        try {
+          obj = pairsToObject(value);
+        } catch (error) {
+          return {
+            issues: [{
+              message: error instanceof Error ? error.message : String(error)
+            }]
+          };
+        }
+        const result = schema["~standard"].validate(obj);
+        if (result instanceof Promise) {
+          return result;
+        }
+        return result;
+      }
+    }
+  };
+}
+export {
+  validateStandard,
+  parseStandard,
+  lua,
+  hashResult,
+  defineScript,
+  VERSION
+};

package/dist/lua-template.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Type-safe Lua tagged template for defining Redis scripts.
+ *
+ * This module provides the `lua` tagged template function that enables
+ * type-safe `${KEYS.name}` and `${ARGV.name}` interpolations, which are
+ * compiled to `KEYS[n]` and `ARGV[n]` at definition time.
+ *
+ * @example
+ * ```ts
+ * import { lua, defineScript } from "upstash-lua"
+ * import { z } from "zod"
+ *
+ * const myScript = defineScript({
+ *   name: "myScript",
+ *   keys: { userKey: z.string() },
+ *   args: { limit: z.number().transform(String) },
+ *   lua: ({ KEYS, ARGV }) => lua`
+ *     local k = ${KEYS.userKey}
+ *     local limit = tonumber(${ARGV.limit})
+ *     return { k, limit }
+ *   `,
+ *   returns: z.tuple([z.string(), z.number()]),
+ * })
+ * ```
+ *
+ * @module lua-template
+ * @since 0.2.0
+ */
+/**
+ * Unique symbol used to brand Lua tokens and compiled templates.
+ * This ensures type safety and prevents accidental misuse.
+ *
+ * @since 0.2.0
+ */
+export declare const LUA_TOKEN: unique symbol;
+/**
+ * A token representing a KEYS or ARGV reference in a Lua template.
+ *
+ * These tokens are created by accessing properties on the typed
+ * `KEYS` and `ARGV` proxy objects passed to the lua function.
+ *
+ * @example
+ * ```ts
+ * // KEYS.userKey produces:
+ * { [LUA_TOKEN]: true, kind: "key", name: "userKey" }
+ *
+ * // ARGV.limit produces:
+ * { [LUA_TOKEN]: true, kind: "arg", name: "limit" }
+ * ```
+ *
+ * @since 0.2.0
+ */
+export interface LuaToken {
+    readonly [LUA_TOKEN]: true;
+    readonly kind: "key" | "arg";
+    readonly name: string;
+}
+/**
+ * The result of the `lua` tagged template function.
+ *
+ * Contains the template strings and interpolated tokens, which are
+ * later compiled into a final Lua string with positional references.
+ *
+ * @since 0.2.0
+ */
+export interface CompiledLua {
+    readonly [LUA_TOKEN]: "compiled";
+    readonly strings: TemplateStringsArray;
+    readonly tokens: readonly LuaToken[];
+}
+/**
+ * A typed proxy object that produces `LuaToken` values for property access.
+ *
+ * Used to type `KEYS` and `ARGV` objects passed to the lua function,
+ * providing autocomplete and compile-time errors for invalid references.
+ *
+ * @typeParam T - The schema record type (keys or args)
+ *
+ * @since 0.2.0
+ */
+export type TokenProxy<T> = {
+    readonly [P in keyof T]: LuaToken;
+};
+/**
+ * Type guard to check if a value is a `LuaToken`.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a `LuaToken`
+ *
+ * @since 0.2.0
+ */
+export declare function isLuaToken(value: unknown): value is LuaToken;
+/**
+ * Type guard to check if a value is a `CompiledLua` template.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a `CompiledLua`
+ *
+ * @since 0.2.0
+ */
+export declare function isCompiledLua(value: unknown): value is CompiledLua;
+/**
+ * Creates a typed proxy that produces `LuaToken` values for any property access.
+ *
+ * @param kind - Whether this proxy is for "key" or "arg" tokens
+ * @returns A proxy object that returns tokens for any property access
+ *
+ * @internal
+ * @since 0.2.0
+ */
+export declare function createTokenProxy<T extends Record<string, unknown>>(kind: "key" | "arg"): TokenProxy<T>;
+/**
+ * Tagged template function for writing type-safe Lua scripts.
+ *
+ * Use this with the `KEYS` and `ARGV` proxies provided by `defineScript`
+ * to create Lua scripts with type-safe key and argument references.
+ *
+ * @param strings - Template literal strings
+ * @param tokens - Interpolated `LuaToken` values from `KEYS.*` or `ARGV.*`
+ * @returns A `CompiledLua` object ready for compilation
+ *
+ * @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 declare function lua(strings: TemplateStringsArray, ...tokens: LuaToken[]): CompiledLua;
+/**
+ * Compiles a `CompiledLua` template into a final Lua string.
+ *
+ * Replaces `KEYS.*` tokens with `KEYS[n]` and `ARGV.*` tokens with `ARGV[n]`
+ * based on the order of keys and args in the schema.
+ *
+ * @param compiled - The compiled lua template from the `lua` tagged template
+ * @param keyNames - Ordered list of key names from the schema
+ * @param argNames - Ordered list of arg names from the schema
+ * @returns The final Lua script string with positional references
+ *
+ * @throws {Error} If a token references a name not in the schema
+ *
+ * @example
+ * ```ts
+ * // Given keyNames = ["userKey"] and argNames = ["limit", "window"]
+ * // ${KEYS.userKey} becomes KEYS[1]
+ * // ${ARGV.limit} becomes ARGV[1]
+ * // ${ARGV.window} becomes ARGV[2]
+ * ```
+ *
+ * @since 0.2.0
+ */
+export declare function compileLua(compiled: CompiledLua, keyNames: readonly string[], argNames: readonly string[]): string;
+//# sourceMappingURL=lua-template.d.ts.map

package/dist/lua-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lua-template.d.ts","sourceRoot":"","sources":["../src/lua-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,MAA4B,CAAA;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,IAAI,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,KAAK,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,UAAU,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAA;CACrC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ;CAAE,CAAA;AAEjE;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAO5D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAOlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,KAAK,GAAG,KAAK,GAClB,UAAU,CAAC,CAAC,CAAC,CAaf;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,GAAG,WAAW,CAiBrF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,WAAW,EACrB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,CA4CR"}