@bb-labs/convex-cache 0.0.1

package/dist/cli/fns/fns/generate-z-schema/utils/build-schema-file.js

@@ -0,0 +1,42 @@
+/**
+ * TypeScript version: used when convex.json has `"fileType": "ts"`.
+ */
+export const buildSchemaFileTs = (schemaEntries) => {
+    // Ensure deterministic ordering by sorting by fnName.
+    const sorted = [...schemaEntries].sort((a, b) => a.fnName.localeCompare(b.fnName));
+    const schemaMapEntries = sorted.map(({ fnName, schemaJson }) => `  "${fnName}": ${JSON.stringify(schemaJson, null, 2)},`);
+    return `// Auto-generated file - do not edit manually
+// This file contains Convex ValidatorJSON definitions derived from \`returns\` in vQuery definitions.
+import type { T_SchemaMap } from "convex-cache";
+
+export const schemaMap: T_SchemaMap = {
+${schemaMapEntries.join("\n")}
+};
+  `;
+};
+/**
+ * JavaScript version: default when not TypeScript.
+ */
+export const buildSchemaFileJs = (schemaEntries) => {
+    const sorted = [...schemaEntries].sort((a, b) => a.fnName.localeCompare(b.fnName));
+    const schemaMapEntries = sorted.map(({ fnName, schemaJson }) => `  "${fnName}": ${JSON.stringify(schemaJson, null, 2)},`);
+    return `// Auto-generated file - do not edit manually
+// This file contains Convex ValidatorJSON definitions derived from \`returns\` in vQuery definitions.
+
+export const schemaMap = {
+${schemaMapEntries.join("\n")}
+};
+  `;
+};
+/**
+ * Declaration file for JS projects: just types.
+ */
+export const buildSchemaDtsFile = () => {
+    return `// Auto-generated file - do not edit manually
+// Type declarations for the generated schemaMap (ValidatorJSON per function).
+
+import type { T_SchemaMap } from "convex-cache";
+
+export declare const schemaMap: T_SchemaMap;
+`;
+};

package/dist/cli/fns/fns/generate-z-schema/utils/extract-schema.d.ts

@@ -0,0 +1,3 @@
+import type { AnyApi } from "convex/server";
+import type { SchemaEntry } from "../generate";
+export declare const extractSchema: (file: string, api: AnyApi, convexDir: string) => Promise<SchemaEntry[]>;

package/dist/cli/fns/fns/generate-z-schema/utils/extract-schema.js

@@ -0,0 +1,84 @@
+// utils/extract-schema.ts
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getFunctionName } from "convex/server";
+import { findFunctionReference } from "./find-fn-ref";
+/**
+ * A Convex query we can inspect:
+ * - must be isQuery
+ * - must be isPublic
+ * - must have exportReturns() function
+ */
+const isConvexFn = (value) => {
+    if (!value || (typeof value !== "function" && typeof value !== "object")) {
+        return false;
+    }
+    const v = value;
+    return Boolean(v.isQuery && v.isPublic && typeof v.exportReturns === "function");
+};
+/**
+ * Returns true if exportReturns() yields a non-null string.
+ * Returns false if null OR if calling exportReturns() throws.
+ */
+const fetchReturnsString = (value) => {
+    try {
+        const result = value.exportReturns?.();
+        return typeof result === "string" && result.length > 0 ? result : null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Parse returnsJsonString → ValidatorJSON
+ * Returns null on parse error.
+ */
+const parseReturnsValidatorJson = ({ returnsString, fnName }) => {
+    try {
+        return JSON.parse(returnsString);
+    }
+    catch (err) {
+        console.warn(`⚠️ Failed to parse return JSON for ${fnName}\nRaw: ${returnsString}`, err);
+        return null;
+    }
+};
+export const extractSchema = async (file, api, convexDir) => {
+    const entries = [];
+    // Load module dynamically
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(file).href));
+    }
+    catch (err) {
+        console.warn(`⚠️ Failed to import ${file}:`, err);
+        return entries;
+    }
+    const relativePath = path.relative(convexDir, file);
+    const modulePath = relativePath.replace(/\.(ts|js)$/, "");
+    for (const [exportName, value] of Object.entries(mod)) {
+        // Check if the value is a Convex query function
+        if (!isConvexFn(value))
+            continue;
+        // Fetch the returns value as a string
+        const returnsString = fetchReturnsString(value);
+        if (!returnsString)
+            continue;
+        // Find the function reference
+        const fnRef = findFunctionReference(api, modulePath, exportName);
+        if (!fnRef)
+            continue;
+        // Get the function name
+        const fnName = getFunctionName(fnRef);
+        // Parse the returns value as a ValidatorJSON
+        const returnsValidatorJson = parseReturnsValidatorJson({ returnsString, fnName });
+        if (!returnsValidatorJson)
+            continue;
+        entries.push({
+            fnName,
+            schemaJson: {
+                returns: returnsValidatorJson,
+            },
+        });
+    }
+    return entries;
+};

package/dist/cli/fns/fns/generate-z-schema/utils/find-fn-ref.d.ts

@@ -0,0 +1,5 @@
+import { AnyApi, FunctionReference } from "convex/server";
+/**
+ * Walk the convex API object to find a FunctionReference.
+ */
+export declare const findFunctionReference: (api: AnyApi, modulePath: string, exportName: string) => FunctionReference<any, any> | undefined;

package/dist/cli/fns/fns/generate-z-schema/utils/find-fn-ref.js

@@ -0,0 +1,27 @@
+/**
+ * Walk the convex API object to find a FunctionReference.
+ */
+export const findFunctionReference = (api, modulePath, exportName) => {
+    try {
+        // Handle both "/" and "\" so this works on Windows too.
+        const parts = modulePath.split(/[\\/]/).filter(Boolean);
+        if (parts.length === 0)
+            return undefined;
+        let current = api;
+        for (const part of parts) {
+            if (!current || typeof current !== "object")
+                return undefined;
+            current = current[part];
+            if (!current)
+                return undefined;
+        }
+        if (exportName === "default") {
+            return current.default || current;
+        }
+        return current[exportName];
+    }
+    catch (error) {
+        console.warn(`Failed to find function reference for ${modulePath}.${exportName}:`, error);
+        return undefined;
+    }
+};

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { dev } from "./fns/dev.js";
+// import pkg from "../package.json" assert { type: "json" };  // optional improvement
+const program = new Command();
+program.name("convex-cache").description("Upload Convex functions & generate Zod schemas on change").version("0.1.0"); // or pkg.version
+program
+    .command("dev")
+    .description("Runs `convex dev` and generates Zod schemas while watching for changes")
+    .option("--schema-only", "Only generate schemas, skip running convex dev", false)
+    .action(async (opts) => {
+    await dev({ schemaOnly: opts.schemaOnly });
+});
+// Let Commander show help by default if no args are provided
+program.showHelpAfterError("(run with --help for usage information)");
+program.showSuggestionAfterError();
+// Use parseAsync so async commands propagate errors
+program.parseAsync(process.argv).catch((err) => {
+    console.error("\n❌ convex-cache failed:");
+    if (err?.message)
+        console.error("  " + err.message);
+    else
+        console.error(err);
+    process.exit(1);
+});

package/dist/cli/lib/convex-config.d.ts

@@ -0,0 +1,21 @@
+export interface ConvexConfig {
+    functions?: string;
+    codegen?: {
+        fileType?: string;
+    };
+}
+/**
+ * Reads the convex.json config file from the current working directory.
+ * Returns null if the file doesn't exist.
+ */
+export declare const readConvexConfig: () => ConvexConfig | null;
+/**
+ * Gets the convex directory path from the config file.
+ * Defaults to "convex" if not specified in the config.
+ */
+export declare const getConvexDir: () => string;
+/**
+ * Determines if TypeScript should be used based on the config file.
+ * Returns true if fileType is "ts" in the codegen section.
+ */
+export declare const shouldUseTs: () => boolean;

package/dist/cli/lib/convex-config.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import fs from "node:fs";
+/**
+ * Reads the convex.json config file from the current working directory.
+ * Returns null if the file doesn't exist.
+ */
+export const readConvexConfig = () => {
+    const configPath = path.join(process.cwd(), "convex.json");
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(configPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        console.warn(`⚠️  Failed to parse convex.json:`, err);
+        return null;
+    }
+};
+/**
+ * Gets the convex directory path from the config file.
+ * Defaults to "convex" if not specified in the config.
+ */
+export const getConvexDir = () => {
+    const config = readConvexConfig();
+    const functionsPath = config?.functions ?? "convex";
+    return path.resolve(functionsPath);
+};
+/**
+ * Determines if TypeScript should be used based on the config file.
+ * Returns true if fileType is "ts" in the codegen section.
+ */
+export const shouldUseTs = () => {
+    const config = readConvexConfig();
+    return config?.codegen?.fileType === "ts";
+};

package/dist/cli/lib/dir-watcher.d.ts

@@ -0,0 +1,49 @@
+export interface DirWatcherOptions {
+    /** Absolute or relative path to the directory to watch. */
+    rootDir: string;
+    /** Whether to watch subdirectories as well. Defaults to true. */
+    recursive?: boolean;
+    /** Debounce time in milliseconds before invoking `onChange`. Defaults to 200ms. */
+    debounceMs?: number;
+    /** Function to determine if a relative path should be ignored. */
+    shouldIgnore?: (relativePath: string) => boolean;
+    /**
+     * Callback invoked when a (debounced) change is detected.
+     * Receives the relative path (from `rootDir`) of the changed file.
+     */
+    onChange: (relativePath: string) => void | Promise<void>;
+}
+/**
+ * A simple debounced directory watcher built on top of `fs.watch`.
+ * It watches a root directory (optionally recursively) and calls `onChange`
+ * after changes settle for `debounceMs` milliseconds.
+ */
+export declare class DirWatcher {
+    private readonly rootDir;
+    private readonly rootLabel;
+    private readonly recursive;
+    private readonly debounceMs;
+    private readonly shouldIgnore?;
+    private readonly onChange;
+    private debounceTimer;
+    private lastRelPath;
+    private watcher;
+    private started;
+    constructor(options: DirWatcherOptions);
+    /**
+     * Start watching the directory.
+     * Exits the process if the root directory does not exist or watcher fails.
+     */
+    start: () => void;
+    /**
+     * Stop watching the directory and clear any pending debounce timer.
+     */
+    stop: () => void;
+    /**
+     * Internal handler for fs.watch events.
+     * Keeps behavior identical to the original implementation:
+     * - debounce on any change
+     * - call `onChange` once with the last changed relative path
+     */
+    private handleFsEvent;
+}

package/dist/cli/lib/dir-watcher.js

@@ -0,0 +1,97 @@
+import fs from "fs";
+import path from "path";
+/**
+ * A simple debounced directory watcher built on top of `fs.watch`.
+ * It watches a root directory (optionally recursively) and calls `onChange`
+ * after changes settle for `debounceMs` milliseconds.
+ */
+export class DirWatcher {
+    constructor(options) {
+        this.debounceTimer = null;
+        this.lastRelPath = null;
+        this.watcher = null;
+        this.started = false;
+        /**
+         * Start watching the directory.
+         * Exits the process if the root directory does not exist or watcher fails.
+         */
+        this.start = () => {
+            if (this.started)
+                return;
+            if (!fs.existsSync(this.rootDir)) {
+                console.error(`watch root not found: ${this.rootDir}`);
+                process.exit(1);
+            }
+            try {
+                this.watcher = fs.watch(this.rootDir, { recursive: this.recursive }, (eventType, filename) => {
+                    this.handleFsEvent(eventType, filename);
+                });
+                this.watcher.on("error", (err) => {
+                    console.error(`fs.watch error for ${this.rootDir}:`, err);
+                    this.stop();
+                    // Keep behavior simple & explicit: fail hard on watcher errors
+                    process.exit(1);
+                });
+                this.started = true;
+            }
+            catch (err) {
+                console.error(`Failed to start fs.watch on ${this.rootDir} (recursive=${this.recursive}):`, err);
+                process.exit(1);
+            }
+        };
+        /**
+         * Stop watching the directory and clear any pending debounce timer.
+         */
+        this.stop = () => {
+            if (this.watcher) {
+                this.watcher.close();
+                this.watcher = null;
+            }
+            if (this.debounceTimer) {
+                clearTimeout(this.debounceTimer);
+                this.debounceTimer = null;
+            }
+            this.lastRelPath = null;
+            this.started = false;
+        };
+        const { rootDir, recursive = true, debounceMs = 200, shouldIgnore, onChange } = options;
+        // Normalize to an absolute path to avoid ambiguity
+        this.rootDir = path.resolve(rootDir);
+        this.rootLabel = path.basename(this.rootDir);
+        this.recursive = recursive;
+        this.debounceMs = debounceMs;
+        this.shouldIgnore = shouldIgnore;
+        this.onChange = onChange;
+    }
+    /**
+     * Internal handler for fs.watch events.
+     * Keeps behavior identical to the original implementation:
+     * - debounce on any change
+     * - call `onChange` once with the last changed relative path
+     */
+    handleFsEvent(_eventType, filename) {
+        if (!filename)
+            return;
+        const rel = filename.toString();
+        if (this.shouldIgnore && this.shouldIgnore(rel))
+            return;
+        this.lastRelPath = rel;
+        console.log(`\n --------- Change detected in ${this.rootLabel}/: ${rel} ---------`);
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            const pathToReport = this.lastRelPath;
+            if (!pathToReport)
+                return;
+            void (async () => {
+                try {
+                    await this.onChange(pathToReport);
+                }
+                catch (err) {
+                    console.error("Error in DirWatcher onChange handler:", err);
+                }
+            })();
+        }, this.debounceMs);
+    }
+}

package/dist/cli/lib/package-cmds.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Produce a command that runs a file with Bun.
+ * Ensures Bun is available before returning.
+ */
+export declare const runFileCmd: (filePath: string) => Promise<string>;
+/**
+ * Produce a command that runs a CLI via Bunx.
+ * Ensures Bun is available before returning.
+ */
+export declare const runCmd: (cmd: string) => Promise<string>;

package/dist/cli/lib/package-cmds.js

@@ -0,0 +1,17 @@
+import { resolveBunOrExit } from "./resolve-bun.js";
+/**
+ * Produce a command that runs a file with Bun.
+ * Ensures Bun is available before returning.
+ */
+export const runFileCmd = async (filePath) => {
+    await resolveBunOrExit();
+    return `bun run ${filePath}`;
+};
+/**
+ * Produce a command that runs a CLI via Bunx.
+ * Ensures Bun is available before returning.
+ */
+export const runCmd = async (cmd) => {
+    await resolveBunOrExit();
+    return `bunx ${cmd}`;
+};

package/dist/cli/lib/resolve-bun.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolve a Bun binary or exit the process with a helpful message.
+ **/
+export declare const resolveBunOrExit: () => Promise<string>;

package/dist/cli/lib/resolve-bun.js

@@ -0,0 +1,24 @@
+import { spawn } from "node:child_process";
+/**
+ * Resolve a Bun binary or exit the process with a helpful message.
+ **/
+export const resolveBunOrExit = async () => {
+    const systemBunOk = await canRunBun("bun");
+    if (systemBunOk)
+        return "bun";
+    console.error("⚠️  Bun is not installed. Please install Bun globally and then re-run this command.");
+    console.error("Docs: https://bun.sh");
+    process.exit(1);
+};
+/**
+ * Check whether a given command behaves like Bun.
+ */
+const canRunBun = async (cmd) => {
+    return await new Promise((resolve) => {
+        const child = spawn(cmd, ["--version"], {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        child.on("exit", (code) => resolve(code === 0));
+        child.on("error", () => resolve(false));
+    });
+};

package/dist/cli/lib/shell-runner.d.ts

@@ -0,0 +1,61 @@
+import { type SpawnOptions } from "child_process";
+export type TaskKind = string;
+export interface ShellRunOptions {
+    /** Human-readable label for logging. */
+    label: string;
+    /** Logical kind/category for the task, used as a key in `currentProcs`. */
+    kind: TaskKind;
+    /** Optional message to log when the command succeeds. */
+    successMessage?: string;
+    /**
+     * Whether to run the command through a shell.
+     * Defaults to true.
+     */
+    shell?: boolean;
+    /**
+     * Extra spawn options (cwd, env, etc.).
+     * `shell` and `stdio` are controlled by ShellRunner.
+     */
+    spawnOptions?: Omit<SpawnOptions, "shell" | "stdio">;
+    /**
+     * Optional AbortSignal for per-run cancellation.
+     */
+    abortSignal?: AbortSignal;
+}
+export declare class ShellRunnerError extends Error {
+    readonly kind: TaskKind;
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    constructor(message: string, kind: TaskKind, code?: number | null, signal?: NodeJS.Signals | null);
+}
+/**
+ * ShellRunner spawns shell commands, tracks them by "kind",
+ * and allows cancelling all running processes.
+ */
+export declare class ShellRunner {
+    private readonly currentProcs;
+    private cancelled;
+    get isCancelled(): boolean;
+    /**
+     * Reset the internal "cancelled" flag back to false.
+     * Does not restart any cancelled processes; it only affects
+     * how subsequent runs behave.
+     */
+    resetCancelled: () => void;
+    /**
+     * Run a shell command with the given options.
+     *
+     * Resolves on successful exit code (0), rejects otherwise,
+     * or if the runner is cancelled / AbortSignal aborts / a process of this kind is already running.
+     */
+    run: (command: string, options: ShellRunOptions) => Promise<void>;
+    /**
+     * Mark the runner as cancelled and send the given signal
+     * (default SIGINT) to all tracked child processes.
+     */
+    cancelAll: (signal?: NodeJS.Signals) => void;
+    /**
+     * Cancel a single running task kind, if present.
+     */
+    cancelKind: (kind: TaskKind, signal?: NodeJS.Signals) => void;
+}

package/dist/cli/lib/shell-runner.js

@@ -0,0 +1,133 @@
+import { spawn } from "child_process";
+export class ShellRunnerError extends Error {
+    constructor(message, kind, code = null, signal = null) {
+        super(message);
+        this.kind = kind;
+        this.code = code;
+        this.signal = signal;
+        this.name = "ShellRunnerError";
+    }
+}
+/**
+ * ShellRunner spawns shell commands, tracks them by "kind",
+ * and allows cancelling all running processes.
+ */
+export class ShellRunner {
+    constructor() {
+        this.currentProcs = new Map();
+        this.cancelled = false;
+        /**
+         * Reset the internal "cancelled" flag back to false.
+         * Does not restart any cancelled processes; it only affects
+         * how subsequent runs behave.
+         */
+        this.resetCancelled = () => {
+            this.cancelled = false;
+        };
+        /**
+         * Run a shell command with the given options.
+         *
+         * Resolves on successful exit code (0), rejects otherwise,
+         * or if the runner is cancelled / AbortSignal aborts / a process of this kind is already running.
+         */
+        this.run = async (command, options) => {
+            const { label, kind, successMessage, shell = true, spawnOptions, abortSignal } = options;
+            // Fast-fail if globally cancelled or already aborted.
+            if (this.cancelled) {
+                throw new ShellRunnerError("ShellRunner is cancelled", kind);
+            }
+            if (abortSignal?.aborted) {
+                throw new ShellRunnerError("Run aborted before start", kind);
+            }
+            // Enforce single process per kind.
+            if (this.currentProcs.has(kind)) {
+                throw new ShellRunnerError(`A task of kind "${kind}" is already running`, kind);
+            }
+            console.log(`\n${label}`);
+            return new Promise((resolve, reject) => {
+                const child = spawn(command, {
+                    shell,
+                    stdio: ["inherit", "inherit", "inherit"],
+                    ...spawnOptions,
+                });
+                this.currentProcs.set(kind, child);
+                // Support AbortSignal-based cancellation
+                const abortHandler = () => {
+                    if (!child.killed) {
+                        child.kill("SIGINT");
+                    }
+                };
+                if (abortSignal) {
+                    abortSignal.addEventListener("abort", abortHandler, { once: true });
+                }
+                let settled = false;
+                const settle = (fn) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    // Cleanup
+                    if (this.currentProcs.get(kind) === child) {
+                        this.currentProcs.delete(kind);
+                    }
+                    if (abortSignal) {
+                        abortSignal.removeEventListener("abort", abortHandler);
+                    }
+                    fn();
+                };
+                child.on("exit", (code, signal) => {
+                    settle(() => {
+                        if (this.cancelled || abortSignal?.aborted) {
+                            return reject(new ShellRunnerError("cancelled", kind, code, signal));
+                        }
+                        if (code === 0) {
+                            if (successMessage) {
+                                console.log(successMessage);
+                            }
+                            return resolve();
+                        }
+                        console.error(`❌ ${label} failed (code=${code ?? "unknown"}, signal=${signal ?? "none"})`);
+                        reject(new ShellRunnerError(`${label} failed with code ${code ?? "unknown"}`, kind, code, signal));
+                    });
+                });
+                child.on("error", (err) => {
+                    settle(() => {
+                        console.error(`❌ Failed to start ${label}:`, err);
+                        reject(err);
+                    });
+                });
+            });
+        };
+        /**
+         * Mark the runner as cancelled and send the given signal
+         * (default SIGINT) to all tracked child processes.
+         */
+        this.cancelAll = (signal = "SIGINT") => {
+            this.cancelled = true;
+            for (const child of this.currentProcs.values()) {
+                try {
+                    child.kill(signal);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        };
+        /**
+         * Cancel a single running task kind, if present.
+         */
+        this.cancelKind = (kind, signal = "SIGINT") => {
+            const child = this.currentProcs.get(kind);
+            if (!child)
+                return;
+            try {
+                child.kill(signal);
+            }
+            catch {
+                // ignore
+            }
+        };
+    }
+    get isCancelled() {
+        return this.cancelled;
+    }
+}

package/dist/convex-cache/adapters/next/fns/build-preloader.d.ts

@@ -0,0 +1,5 @@
+import { Q_Query } from "../../../core/types/types/query";
+import { PQ_Query } from "../../../core/types/types/paginated-query";
+import { PreloadQueryReturn, T_PreloadQueryParams } from "./preload-query";
+import { T_SchemaMap } from "../../../types/schema-map";
+export declare function buildPreloader(schemaMap: T_SchemaMap): <Q extends Q_Query | PQ_Query>(params: Omit<T_PreloadQueryParams<Q>, "schemaMap">) => Promise<PreloadQueryReturn<Q>>;

package/dist/convex-cache/adapters/next/fns/build-preloader.js

@@ -0,0 +1,6 @@
+import { preloadQuery } from "./preload-query";
+export function buildPreloader(schemaMap) {
+    return function preloadQueryBound(params) {
+        return preloadQuery({ ...params, schemaMap });
+    };
+}