@thewhateverapp/platform 0.8.0 → 0.9.0

package/dist/keyspace/index.js

@@ -0,0 +1,929 @@
+/**
+ * Keyspace API
+ *
+ * Redis-inspired shared state service providing counters, KV, queues,
+ * sets, leaderboards, hashes, rate limiting, and distributed locks.
+ *
+ * @example
+ * ```typescript
+ * import { getCloudflareContext } from '@opennextjs/cloudflare';
+ * import { configurePlatformEnv, getKeyspace } from '@thewhateverapp/platform';
+ *
+ * export async function POST(req: NextRequest) {
+ *   configurePlatformEnv(() => getCloudflareContext().env);
+ *
+ *   const keyspace = await getKeyspace();
+ *
+ *   // Increment counter
+ *   const count = await keyspace.counter('visitors').increment();
+ *
+ *   // Store value with TTL
+ *   await keyspace.kv.set('session', { user: 'john' }, 3600);
+ *
+ *   // Add to leaderboard
+ *   await keyspace.leaderboard('scores').add('player1', 100);
+ *
+ *   return NextResponse.json({ count });
+ * }
+ * ```
+ */
+import { getPlatformEnv, isPlatformEnvConfigured } from '../env';
+/**
+ * Default base URL for HTTP-based keyspace access
+ */
+const DEFAULT_KEYSPACE_URL = 'https://keyspace.thewhatever.app';
+/**
+ * Internal helper to execute operations against the DO
+ */
+async function executeOp(stub, operation) {
+    const response = await stub.fetch('http://internal/op', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(operation),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+        throw new Error(`Keyspace operation failed: ${error.error}`);
+    }
+    return (await response.json());
+}
+/**
+ * Cloudflare Durable Object-backed Keyspace Provider
+ */
+class CloudflareKeyspace {
+    stub;
+    constructor(stub) {
+        this.stub = stub;
+    }
+    counter(name, scope) {
+        const stub = this.stub;
+        return {
+            async increment(by = 1) {
+                const result = await executeOp(stub, {
+                    type: 'counter',
+                    action: 'increment',
+                    name,
+                    scope,
+                    value: by,
+                });
+                return result.data ?? 0;
+            },
+            async decrement(by = 1) {
+                const result = await executeOp(stub, {
+                    type: 'counter',
+                    action: 'decrement',
+                    name,
+                    scope,
+                    value: by,
+                });
+                return result.data ?? 0;
+            },
+            async get() {
+                const result = await executeOp(stub, {
+                    type: 'counter',
+                    action: 'get',
+                    name,
+                    scope,
+                });
+                return result.data ?? 0;
+            },
+            async set(value) {
+                const result = await executeOp(stub, {
+                    type: 'counter',
+                    action: 'set',
+                    name,
+                    scope,
+                    value,
+                });
+                return result.data ?? value;
+            },
+            async reset() {
+                await executeOp(stub, {
+                    type: 'counter',
+                    action: 'reset',
+                    name,
+                    scope,
+                });
+                return 0;
+            },
+        };
+    }
+    get kv() {
+        const stub = this.stub;
+        return {
+            async get(key) {
+                const result = await executeOp(stub, {
+                    type: 'kv',
+                    action: 'get',
+                    key,
+                });
+                return result.data ?? null;
+            },
+            async set(key, value, ttlSeconds) {
+                await executeOp(stub, {
+                    type: 'kv',
+                    action: 'set',
+                    key,
+                    value,
+                    ttlSeconds,
+                });
+            },
+            async delete(key) {
+                await executeOp(stub, {
+                    type: 'kv',
+                    action: 'delete',
+                    key,
+                });
+            },
+            async has(key) {
+                const result = await executeOp(stub, {
+                    type: 'kv',
+                    action: 'has',
+                    key,
+                });
+                return result.data ?? false;
+            },
+        };
+    }
+    queue(name) {
+        const stub = this.stub;
+        return {
+            async enqueue(value) {
+                const result = await executeOp(stub, {
+                    type: 'queue',
+                    action: 'enqueue',
+                    name,
+                    value,
+                });
+                return result.data ?? 0;
+            },
+            async dequeue() {
+                const result = await executeOp(stub, {
+                    type: 'queue',
+                    action: 'dequeue',
+                    name,
+                });
+                return result.data ?? null;
+            },
+            async readRange(start = 0, stop = 9) {
+                const result = await executeOp(stub, {
+                    type: 'queue',
+                    action: 'readRange',
+                    name,
+                    start,
+                    stop,
+                });
+                return result.data ?? [];
+            },
+            async length() {
+                const result = await executeOp(stub, {
+                    type: 'queue',
+                    action: 'length',
+                    name,
+                });
+                return result.data ?? 0;
+            },
+            async clear() {
+                await executeOp(stub, {
+                    type: 'queue',
+                    action: 'clear',
+                    name,
+                });
+            },
+        };
+    }
+    set(name) {
+        const stub = this.stub;
+        return {
+            async add(value) {
+                const result = await executeOp(stub, {
+                    type: 'set',
+                    action: 'add',
+                    name,
+                    value,
+                });
+                return result.data ?? 0;
+            },
+            async remove(value) {
+                const result = await executeOp(stub, {
+                    type: 'set',
+                    action: 'remove',
+                    name,
+                    value,
+                });
+                return result.data ?? 0;
+            },
+            async has(value) {
+                const result = await executeOp(stub, {
+                    type: 'set',
+                    action: 'has',
+                    name,
+                    value,
+                });
+                return result.data ?? false;
+            },
+            async members() {
+                const result = await executeOp(stub, {
+                    type: 'set',
+                    action: 'members',
+                    name,
+                });
+                return result.data ?? [];
+            },
+            async size() {
+                const result = await executeOp(stub, {
+                    type: 'set',
+                    action: 'size',
+                    name,
+                });
+                return result.data ?? 0;
+            },
+        };
+    }
+    leaderboard(name) {
+        const stub = this.stub;
+        return {
+            async add(member, score) {
+                const result = await executeOp(stub, {
+                    type: 'leaderboard',
+                    action: 'add',
+                    name,
+                    member,
+                    score,
+                });
+                return result.data ?? 0;
+            },
+            async increment(member, by = 1) {
+                const result = await executeOp(stub, {
+                    type: 'leaderboard',
+                    action: 'increment',
+                    name,
+                    member,
+                    score: by,
+                });
+                return result.data ?? 0;
+            },
+            async getRange(start = 0, stop = 9) {
+                const result = await executeOp(stub, {
+                    type: 'leaderboard',
+                    action: 'getRange',
+                    name,
+                    start,
+                    stop,
+                });
+                return result.data ?? [];
+            },
+            async getRank(member) {
+                const result = await executeOp(stub, {
+                    type: 'leaderboard',
+                    action: 'getRank',
+                    name,
+                    member,
+                });
+                return result.data ?? -1;
+            },
+            async getScore(member) {
+                const result = await executeOp(stub, {
+                    type: 'leaderboard',
+                    action: 'getScore',
+                    name,
+                    member,
+                });
+                return result.data ?? null;
+            },
+            async remove(member) {
+                await executeOp(stub, {
+                    type: 'leaderboard',
+                    action: 'remove',
+                    name,
+                    member,
+                });
+            },
+        };
+    }
+    hash(key) {
+        const stub = this.stub;
+        return {
+            async set(field, value) {
+                await executeOp(stub, {
+                    type: 'hash',
+                    action: 'set',
+                    key,
+                    field,
+                    value,
+                });
+            },
+            async get(field) {
+                const result = await executeOp(stub, {
+                    type: 'hash',
+                    action: 'get',
+                    key,
+                    field,
+                });
+                return result.data ?? null;
+            },
+            async getAll() {
+                const result = await executeOp(stub, {
+                    type: 'hash',
+                    action: 'getAll',
+                    key,
+                });
+                return result.data ?? {};
+            },
+            async delete(field) {
+                await executeOp(stub, {
+                    type: 'hash',
+                    action: 'delete',
+                    key,
+                    field,
+                });
+            },
+            async increment(field, by = 1) {
+                const result = await executeOp(stub, {
+                    type: 'hash',
+                    action: 'increment',
+                    key,
+                    field,
+                    value: by,
+                });
+                return result.data ?? 0;
+            },
+        };
+    }
+    rateLimit(key) {
+        const stub = this.stub;
+        return {
+            async check(limit, windowSeconds) {
+                const result = await executeOp(stub, {
+                    type: 'rateLimit',
+                    action: 'check',
+                    key,
+                    limit,
+                    windowSeconds,
+                });
+                return (result.data ?? {
+                    allowed: false,
+                    remaining: 0,
+                    resetAt: Date.now(),
+                    limit,
+                });
+            },
+        };
+    }
+    lock(name) {
+        const stub = this.stub;
+        return {
+            async acquire(ttlSeconds = 30, owner) {
+                const result = await executeOp(stub, {
+                    type: 'lock',
+                    action: 'acquire',
+                    name,
+                    ttlSeconds,
+                    owner,
+                });
+                return (result.data ?? {
+                    acquired: false,
+                    owner: '',
+                    expiresAt: 0,
+                });
+            },
+            async release(owner) {
+                const result = await executeOp(stub, {
+                    type: 'lock',
+                    action: 'release',
+                    name,
+                    owner,
+                });
+                return result.data ?? { released: false };
+            },
+            async check() {
+                const result = await executeOp(stub, {
+                    type: 'lock',
+                    action: 'check',
+                    name,
+                });
+                return result.data ?? { locked: false };
+            },
+        };
+    }
+    async batch(_operations) {
+        // For now, execute sequentially. Can optimize with /batch endpoint later
+        const results = [];
+        for (const op of _operations) {
+            results.push(await op());
+        }
+        return results;
+    }
+    async isHealthy() {
+        try {
+            const response = await this.stub.fetch('http://internal/health');
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Internal helper to execute operations via HTTP
+ */
+async function executeHttpOp(baseUrl, apiKey, operation, fetchFn = globalThis.fetch) {
+    const response = await fetchFn(`${baseUrl}/op`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(operation),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+        throw new Error(`Keyspace operation failed: ${error.error}`);
+    }
+    return (await response.json());
+}
+/**
+ * HTTP-based Keyspace Provider
+ *
+ * Used when service bindings are not available (e.g., external services, testing).
+ * Authenticates via Platform API key (JWT).
+ */
+class HttpKeyspace {
+    baseUrl;
+    apiKey;
+    fetchFn;
+    constructor(config) {
+        this.baseUrl = config.baseUrl || DEFAULT_KEYSPACE_URL;
+        this.apiKey = config.apiKey;
+        this.fetchFn = config.fetch || globalThis.fetch;
+    }
+    counter(name, scope) {
+        const { baseUrl, apiKey, fetchFn } = this;
+        return {
+            async increment(by = 1) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'counter',
+                    action: 'increment',
+                    name,
+                    scope,
+                    value: by,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async decrement(by = 1) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'counter',
+                    action: 'decrement',
+                    name,
+                    scope,
+                    value: by,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async get() {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'counter',
+                    action: 'get',
+                    name,
+                    scope,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async set(value) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'counter',
+                    action: 'set',
+                    name,
+                    scope,
+                    value,
+                }, fetchFn);
+                return result.data ?? value;
+            },
+            async reset() {
+                await executeHttpOp(baseUrl, apiKey, {
+                    type: 'counter',
+                    action: 'reset',
+                    name,
+                    scope,
+                }, fetchFn);
+                return 0;
+            },
+        };
+    }
+    get kv() {
+        const { baseUrl, apiKey, fetchFn } = this;
+        return {
+            async get(key) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'kv',
+                    action: 'get',
+                    key,
+                }, fetchFn);
+                return result.data ?? null;
+            },
+            async set(key, value, ttlSeconds) {
+                await executeHttpOp(baseUrl, apiKey, {
+                    type: 'kv',
+                    action: 'set',
+                    key,
+                    value,
+                    ttlSeconds,
+                }, fetchFn);
+            },
+            async delete(key) {
+                await executeHttpOp(baseUrl, apiKey, {
+                    type: 'kv',
+                    action: 'delete',
+                    key,
+                }, fetchFn);
+            },
+            async has(key) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'kv',
+                    action: 'has',
+                    key,
+                }, fetchFn);
+                return result.data ?? false;
+            },
+        };
+    }
+    queue(name) {
+        const { baseUrl, apiKey, fetchFn } = this;
+        return {
+            async enqueue(value) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'queue',
+                    action: 'enqueue',
+                    name,
+                    value,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async dequeue() {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'queue',
+                    action: 'dequeue',
+                    name,
+                }, fetchFn);
+                return result.data ?? null;
+            },
+            async readRange(start = 0, stop = 9) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'queue',
+                    action: 'readRange',
+                    name,
+                    start,
+                    stop,
+                }, fetchFn);
+                return result.data ?? [];
+            },
+            async length() {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'queue',
+                    action: 'length',
+                    name,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async clear() {
+                await executeHttpOp(baseUrl, apiKey, {
+                    type: 'queue',
+                    action: 'clear',
+                    name,
+                }, fetchFn);
+            },
+        };
+    }
+    set(name) {
+        const { baseUrl, apiKey, fetchFn } = this;
+        return {
+            async add(value) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'set',
+                    action: 'add',
+                    name,
+                    value,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async remove(value) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'set',
+                    action: 'remove',
+                    name,
+                    value,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async has(value) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'set',
+                    action: 'has',
+                    name,
+                    value,
+                }, fetchFn);
+                return result.data ?? false;
+            },
+            async members() {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'set',
+                    action: 'members',
+                    name,
+                }, fetchFn);
+                return result.data ?? [];
+            },
+            async size() {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'set',
+                    action: 'size',
+                    name,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+        };
+    }
+    leaderboard(name) {
+        const { baseUrl, apiKey, fetchFn } = this;
+        return {
+            async add(member, score) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'leaderboard',
+                    action: 'add',
+                    name,
+                    member,
+                    score,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async increment(member, by = 1) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'leaderboard',
+                    action: 'increment',
+                    name,
+                    member,
+                    score: by,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+            async getRange(start = 0, stop = 9) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'leaderboard',
+                    action: 'getRange',
+                    name,
+                    start,
+                    stop,
+                }, fetchFn);
+                return result.data ?? [];
+            },
+            async getRank(member) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'leaderboard',
+                    action: 'getRank',
+                    name,
+                    member,
+                }, fetchFn);
+                return result.data ?? -1;
+            },
+            async getScore(member) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'leaderboard',
+                    action: 'getScore',
+                    name,
+                    member,
+                }, fetchFn);
+                return result.data ?? null;
+            },
+            async remove(member) {
+                await executeHttpOp(baseUrl, apiKey, {
+                    type: 'leaderboard',
+                    action: 'remove',
+                    name,
+                    member,
+                }, fetchFn);
+            },
+        };
+    }
+    hash(key) {
+        const { baseUrl, apiKey, fetchFn } = this;
+        return {
+            async set(field, value) {
+                await executeHttpOp(baseUrl, apiKey, {
+                    type: 'hash',
+                    action: 'set',
+                    key,
+                    field,
+                    value,
+                }, fetchFn);
+            },
+            async get(field) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'hash',
+                    action: 'get',
+                    key,
+                    field,
+                }, fetchFn);
+                return result.data ?? null;
+            },
+            async getAll() {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'hash',
+                    action: 'getAll',
+                    key,
+                }, fetchFn);
+                return result.data ?? {};
+            },
+            async delete(field) {
+                await executeHttpOp(baseUrl, apiKey, {
+                    type: 'hash',
+                    action: 'delete',
+                    key,
+                    field,
+                }, fetchFn);
+            },
+            async increment(field, by = 1) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'hash',
+                    action: 'increment',
+                    key,
+                    field,
+                    value: by,
+                }, fetchFn);
+                return result.data ?? 0;
+            },
+        };
+    }
+    rateLimit(key) {
+        const { baseUrl, apiKey, fetchFn } = this;
+        return {
+            async check(limit, windowSeconds) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'rateLimit',
+                    action: 'check',
+                    key,
+                    limit,
+                    windowSeconds,
+                }, fetchFn);
+                return (result.data ?? {
+                    allowed: false,
+                    remaining: 0,
+                    resetAt: Date.now(),
+                    limit,
+                });
+            },
+        };
+    }
+    lock(name) {
+        const { baseUrl, apiKey, fetchFn } = this;
+        return {
+            async acquire(ttlSeconds = 30, owner) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'lock',
+                    action: 'acquire',
+                    name,
+                    ttlSeconds,
+                    owner,
+                }, fetchFn);
+                return (result.data ?? {
+                    acquired: false,
+                    owner: '',
+                    expiresAt: 0,
+                });
+            },
+            async release(owner) {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'lock',
+                    action: 'release',
+                    name,
+                    owner,
+                }, fetchFn);
+                return result.data ?? { released: false };
+            },
+            async check() {
+                const result = await executeHttpOp(baseUrl, apiKey, {
+                    type: 'lock',
+                    action: 'check',
+                    name,
+                }, fetchFn);
+                return result.data ?? { locked: false };
+            },
+        };
+    }
+    async batch(_operations) {
+        // For now, execute sequentially. Can optimize with /batch endpoint later
+        const results = [];
+        for (const op of _operations) {
+            results.push(await op());
+        }
+        return results;
+    }
+    async isHealthy() {
+        try {
+            const response = await this.fetchFn(`${this.baseUrl}/health`);
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Create a Keyspace instance using HTTP with API key authentication
+ *
+ * Use this when service bindings are not available (e.g., external services, testing).
+ * The API key must have 'keyspace' or '*' permission.
+ *
+ * @param config - HTTP configuration with API key
+ * @returns Keyspace provider instance
+ *
+ * @example
+ * ```typescript
+ * const keyspace = createKeyspaceHttp({
+ *   apiKey: 'wtvr_jwt_eyJ...',
+ *   baseUrl: 'https://keyspace.thewhatever.app', // optional
+ * });
+ *
+ * const count = await keyspace.counter('visitors').increment();
+ * ```
+ */
+export function createKeyspaceHttp(config) {
+    if (!config.apiKey) {
+        throw new Error('API key is required for HTTP-based keyspace access');
+    }
+    return new HttpKeyspace(config);
+}
+/**
+ * Get a Keyspace instance for the current request
+ *
+ * @param reqOrEnv - Optional: object with env property, or env object directly.
+ *                   If not provided, uses the env configured via configurePlatformEnv().
+ * @returns Keyspace provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using configured env (recommended)
+ * configurePlatformEnv(() => getCloudflareContext().env);
+ * const keyspace = await getKeyspace();
+ *
+ * // Or pass env directly
+ * const keyspace = await getKeyspace({ env });
+ * const keyspace = await getKeyspace(env);
+ * ```
+ */
+export async function getKeyspace(reqOrEnv) {
+    let env;
+    // If no argument provided, use the configured env provider
+    if (!reqOrEnv) {
+        if (!isPlatformEnvConfigured()) {
+            throw new Error('getKeyspace() called without env and configurePlatformEnv() was not called. ' +
+                'Either pass env directly: getKeyspace({ env }) or call configurePlatformEnv(() => getCloudflareContext().env) first.');
+        }
+        env = getPlatformEnv();
+    }
+    else if ('env' in reqOrEnv) {
+        env = reqOrEnv.env;
+    }
+    else if ('KEYSPACE' in reqOrEnv) {
+        // Direct env object
+        env = reqOrEnv;
+    }
+    else {
+        env = reqOrEnv.env;
+    }
+    if (!env) {
+        throw new Error('No environment found. Ensure you are running in edge runtime.');
+    }
+    // Check for KEYSPACE Durable Object binding
+    if (!env.KEYSPACE) {
+        throw new Error('No KEYSPACE Durable Object binding found. ' +
+            'Add a service binding to the keyspace-do worker in your wrangler.jsonc:\n' +
+            '  "services": [{ "binding": "KEYSPACE", "service": "keyspace-do", "entrypoint": "Keyspace" }]');
+    }
+    // Get APP_ID for isolation (one DO per app)
+    const appId = env.APP_ID || 'default';
+    // Get Durable Object ID from app ID (deterministic)
+    const id = env.KEYSPACE.idFromName(appId);
+    const stub = env.KEYSPACE.get(id);
+    return new CloudflareKeyspace(stub);
+}
+/**
+ * Create a Keyspace instance directly (for advanced usage)
+ *
+ * @param env - Environment with KEYSPACE binding
+ * @param appId - Optional app ID for isolation (defaults to env.APP_ID or 'default')
+ *
+ * @example
+ * ```typescript
+ * const keyspace = createKeyspace({ KEYSPACE: env.KEYSPACE }, 'my-app-id');
+ * await keyspace.counter('visitors').increment();
+ * ```
+ */
+export function createKeyspace(env, appId) {
+    if (!env.KEYSPACE) {
+        throw new Error('No KEYSPACE Durable Object binding found.');
+    }
+    const resolvedAppId = appId || env.APP_ID || 'default';
+    const id = env.KEYSPACE.idFromName(resolvedAppId);
+    const stub = env.KEYSPACE.get(id);
+    return new CloudflareKeyspace(stub);
+}
+//# sourceMappingURL=index.js.map