pomai-cache

Pomai Cache is a lightweight, production-ready caching SDK focused on JavaScript and TypeScript applications. The SDK provides a small, consistent client for storing and retrieving cached values so your app can deliver faster responses and reduce backend load. pomai-cache is designed to integrate easily into Node.js, browser, and serverless environments.

Visit the API key generator (Beta, free for early users): https://pomai-cache.cookiescooker.click

Highlights

• SDK designed specifically for JavaScript and TypeScript projects
• Simple client API for set/get/delete, atomic counters and TTL management
• Auto-discovery of service endpoint (no need to manually pass discovery URL)
• Works in Browser, Node.js, Deno, Bun and many serverless platforms
• Observability hooks for metrics and instrumentation
• Small surface area, easy to adopt in existing apps

Quick start

1. Install

npm:

npm install @autocookie/pomai-cache

yarn:

yarn add @autocookie/pomai-cache

2. Provide your API key

Set your API key with an environment variable (recommended) or pass it to the client directly.

Unix/macOS:

export POMAI_API_KEY="your_api_key_here"

Windows (PowerShell):

$env:POMAI_API_KEY="your_api_key_here"

3. Initialize the client

Note: The SDK performs discovery automatically. You generally only need to pass your API key and optional client-level options (for example, a custom timeout). You do not need to pass a discovery URL.

JavaScript (CommonJS)

const { PomaiClient } = require('@autocookie/pomai-cache');

const client = new PomaiClient(process.env.POMAI_API_KEY || 'YOUR_API_KEY', {
  timeout: 5000 // optional
});

TypeScript (ESM)

import { PomaiClient, PomaiConfig } from '@autocookie/pomai-cache';

const config: PomaiConfig = { timeout: 5000 };
const client = new PomaiClient(process.env.POMAI_API_KEY || '', config);

Example usage (Node / TypeScript)

import { PomaiClient } from '@autocookie/pomai-cache';
import dotenv from 'dotenv';
dotenv.config();

const client = new PomaiClient(process.env.POMAI_API_KEY || '', { timeout: 5000 });

async function main() {
  // Store a string
  await client.set('greeting', 'Hello Pomai from TypeScript!');
  
  // Store JSON (automatically stringified)
  await client.set('user:101', { id: 101, name: 'Auto Cookies' }, { ttl: 300 });

  // Read values
  const greeting = await client.get('greeting'); // returns string | null
  const user = await client.getJSON<{ name: string }>('user:101'); // returns typed object | null

  // Atomic counter
  const views = await client.incr('page:home:views');

  // TTL (seconds remaining): -2 = key not found, -1 = no TTL
  const ttl = await client.ttl('user:101');

  console.log({ greeting, user, views, ttl });
}

main().catch(console.error);

Core API (overview)

• constructor PomaiClient(apiKey: string, config?: PomaiConfig)
  • PomaiConfig commonly contains:
    • timeout?: number — request timeout in milliseconds (default 10000)
    • discoveryUrl?: string — optional override (rarely needed; SDK auto-discovers)
• connect(): Promise — optional warm-up/discovery call (SDK will auto-call when needed)
• get(key: string): Promise<string | null>
• getJSON(key: string): Promise<T | null>
• set(key: string, value: string | object | number | boolean, options?: { ttl?: number }): Promise
• delete(key: string): Promise
• incr(key: string, delta?: number): Promise
• decr(key: string, delta?: number): Promise
• ttl(key: string): Promise — returns seconds remaining, -1 for no TTL, -2 if key not exists
• ping(): Promise — health check

Behavior notes

• JSON values are automatically stringified on set and parsed on getJSON.
• The SDK caches the discovered service base URL in browser localStorage (when available) to speed up subsequent requests.
• If a request times out or fails, the returned Promise will reject; callers should handle errors appropriately.

Configuration options

• apiKey: provided to constructor (or via environment variable)
• timeout: request timeout in ms
• discoveryUrl (optional): only necessary if you want to force a specific discovery endpoint (default: SDK-managed)

Observability The SDK is small and exposes clear request paths so you can instrument:

• Hit / miss ratios (derived from your integration)
• Request latencies and errors
• Eviction and TTL metrics (where backend exposes these) Integrate with Prometheus, Datadog, Sentry, or your preferred observability platform.

Best practices

• Use namespaces or key prefixes (e.g., env/service identifiers) to avoid key collisions across environments.
• Choose TTLs according to data freshness and traffic patterns; monitor hit/miss ratios to tune.
• Avoid storing very large blobs in cache. If you must, consider storing references and retrieving large content separately.
• Keep API keys secret. Use environment variables or secret managers in production.

Supported environments

• Node.js
• Browser (modern browsers with fetch + localStorage)
• Deno, Bun
• Cloudflare Workers and many serverless platforms (where fetch is available)

Security

• Keep API keys out of source control and CI logs.
• When using from a browser, follow CORS and network security best practices. Prefer server-side usage for sensitive data.
• Use different API keys or namespaces for production vs. staging.

Examples and tests Look for example files and tests in the repository to see complete usage patterns. The top-level example.ts demonstrates typical operations (set/get/incr/ttl).

Contributing Contributions are welcome. Please:

1. Open an issue to discuss large changes or new features.
2. Create a pull request with a clear description and tests for code changes.
3. Follow repository coding conventions and add documentation for new APIs.

• Report bugs or request features: https://github.com/AutoCookies/pomai-cache/issues
• Pull requests: https://github.com/AutoCookies/pomai-cache/pulls

License This project is released under the MIT License. See the LICENSE file for full terms.