@devindex/api-kit 0.2.0 → 0.3.1

package/README.md

@@ -9,8 +9,8 @@ driver from the environment.
 npm install @devindex/api-kit
 ```
 
-Node `>=22`. The memory drivers need no external service. BullMQ drivers load their optional peers
-only on first use:
+Node `>=22`. The memory drivers need no external service. The Redis-backed drivers load their
+optional peers only on first use:
 
 ```bash
 npm install bullmq ioredis
@@ -103,7 +103,8 @@ The status is the error's own `status` when it has one, otherwise `STATUS_BY_COD
 
 Inbound `x-request-id` is reused only when it is a valid UUID, otherwise a fresh v4 is generated; the
 id is always echoed back. `schema.js` ships ODM-agnostic JSON-Schema helpers — `objectSchema`,
-`stringSchema`, `pageQuery`, `email`, `dateTime`, `dateKey`, `clock`.
+`stringSchema`, `pageQuery`, `pageResponse`, `email`, `dateTime`, `dateKey`, `clock` (see
+[Pagination](#pagination)).
 
 ### CORS and security headers
 
@@ -145,6 +146,54 @@ await createApp({ helmet: { contentSecurityPolicy: { useDefaults: true } }, rout
 Anything else — rate limits, compression — still goes through `plugins`, which registers after these
 and before the routes.
 
+### Pagination
+
+Offset pagination in two shapes, `{ items, hasMore }` and `{ items, hasMore, total }`, over one rule:
+**the query fetches `limit + 1` rows** and `paginate` slices the extra one off. The kit never runs the
+query — `skip`/`limit` belong to Mongoose, `offset`/`limit` to a SQL builder, a cursor to an upstream
+API — so it only does the arithmetic and the shape, and works with all of them.
+
+```js
+import { paginate } from '@devindex/api-kit/http';
+
+const rows = await Order.find(filter).skip(offset).limit(limit + 1);
+return paginate(rows, limit);        // { items, hasMore }
+```
+
+A resource that really needs the count passes it as the third argument, and gets `total` in the
+response:
+
+```js
+const [rows, total] = await Promise.all([
+  Order.find(filter).skip(offset).limit(limit + 1),
+  Order.countDocuments(filter),
+]);
+return paginate(rows, limit, total); // { items, hasMore, total }
+```
+
+`hasMore` always comes from the extra row, never from `total`. Deriving it from the count would make
+it depend on two queries that can disagree — a document inserted between them, and the flag promises
+a page that is not there.
+
+`pageQuery` and `pageResponse` are the two ends of the contract. The response schema is not optional
+decoration: Fastify strips whatever it does not declare, so a missing `hasMore` there silently
+disappears from a correct payload.
+
+```js
+import { pageQuery, pageResponse } from '@devindex/api-kit/http';
+
+instance.get('/orders', {
+  schema: {
+    querystring: pageQuery({ maxLimit: 50 }),
+    response: { 200: pageResponse(orderSchema) },
+  },
+}, async (req) => orders.list(req.query));
+```
+
+`pageQuery` applies the defaults (`limit` 20, `offset` 0), so the handler always reads two integers.
+`pageResponse(items, { total: true })` adds `total` to the schema — pass it wherever `paginate` gets
+a count.
+
 ## `./context`
 
 An isolated `AsyncLocalStorage` store, owned by the service, so two services in one process never
@@ -425,6 +474,68 @@ Every Redis replica upserts the same scheduler and starts an equivalent Worker.
 leader; BullMQ coordinates which Worker receives each occurrence. A new occurrence is produced when
 the previous one starts, so global concurrency serializes slow runs rather than overlapping them.
 
+## `./cache`
+
+Key/value cache with one contract over two stores:
+
+```js
+import { createCache } from '@devindex/api-kit/cache';
+
+const cache = createCache({
+  driver: 'redis',
+  redisUrl,
+  prefix: 'billing',
+  ttl: 300_000,
+  logger,
+});
+
+await cache.start();
+
+const plan = await cache.wrap(`plan:${planId}`, () => plans.findById(planId));
+
+await cache.set(`quote:${userId}`, quote, { ttl: 60_000 });
+const quote = await cache.get(`quote:${userId}`);
+const known = await cache.has(`quote:${userId}`);
+
+await plans.update(planId, changes);
+await cache.delete(`plan:${planId}`);
+
+await cache.stop();
+```
+
+Every key is namespaced by `prefix`, so `plan:42` is stored as `billing:plan:42`. `ttl` is in
+milliseconds and `0` never expires; the cache default is overridable on each write.
+
+Values must be JSON-serializable. `undefined` reports a miss and is never stored — writing it
+throws — while `null` is a value like any other, so `get()` returns `null` and `has()` returns
+`true` for it. Both drivers keep the serialized form, so the object the memory driver returns can
+be mutated without corrupting what is cached.
+
+`wrap()` returns the cached value or runs the loader once, stores the result and returns it; a
+loader that resolves `undefined` is not cached. Concurrent misses on the same key run one loader
+each — the cache does not collapse them.
+
+### Failures
+
+A cache read or write is an optimization and never fails a request: with the store unreachable,
+`get()` and `has()` report a miss and `set()` logs a warning, so the caller falls back to its
+source. `delete()` is the exception and rejects. An invalidation that did not happen keeps serving
+stale data until the TTL expires, which only the caller can weigh — `.catch(() => {})` says so
+explicitly.
+
+### Driver guarantees
+
+| | `memory` | `redis` |
+|---|---|---|
+| External service | None | Redis |
+| Scope | One private cache per replica | One cache shared by every replica |
+| Survives restart | No | Yes |
+| Expiration | On read | Owned by Redis |
+| Size bound | None | Redis eviction policy |
+
+The memory driver frees an entry only when it is read after expiring, so a key written and never
+read again occupies memory until `stop()`. Keep it for development, tests and small derived values.
+
 ## `./env`
 
 `createEnvReader()` reads `process.env` and **collects** what is wrong instead of failing on the

package/cache/drivers/memory.js

@@ -0,0 +1,43 @@
+/**
+ * In-process store for tests and local runs. Entries expire on read and are lost
+ * with the process.
+ *
+ * @return {object} A store: start, get, has, set, delete and stop.
+ */
+export function memoryStore() {
+  const entries = new Map();
+
+  function read(key) {
+    const entry = entries.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt !== 0 && entry.expiresAt <= Date.now()) {
+      entries.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  return {
+    async start() {},
+
+    async get(key) {
+      return read(key);
+    },
+
+    async has(key) {
+      return read(key) !== undefined;
+    },
+
+    async set(key, value, ttl) {
+      entries.set(key, { value, expiresAt: ttl === 0 ? 0 : Date.now() + ttl });
+    },
+
+    async delete(key) {
+      return entries.delete(key);
+    },
+
+    async stop() {
+      entries.clear();
+    },
+  };
+}

package/cache/drivers/redis.js

@@ -0,0 +1,53 @@
+import { noopLogger } from '../../internal/logger.js';
+import { loadIoredis, redisConnection } from '../../internal/redis.js';
+
+/**
+ * Shared store on Redis, with expiration owned by Redis itself.
+ *
+ * @param {object} options
+ * @param {string} options.redisUrl
+ * @param {object} [options.logger]
+ * @return {object} A store: start, get, has, set, delete and stop.
+ */
+export function redisStore({ redisUrl, logger = noopLogger } = {}) {
+  const connection = redisConnection(redisUrl);
+  let client;
+
+  return {
+    async start() {
+      const { default: Redis } = await loadIoredis();
+      client = new Redis(connection);
+      // ioredis emits 'error' on the client, and an EventEmitter with no 'error'
+      // listener throws: a dropped connection would kill the process the cache
+      // is only supposed to make faster.
+      client.on('error', (error) => logger.warn({ err: error }, 'cache connection error'));
+    },
+
+    async get(key) {
+      const value = await client.get(key);
+      return value === null ? undefined : value;
+    },
+
+    async has(key) {
+      return await client.exists(key) > 0;
+    },
+
+    async set(key, value, ttl) {
+      if (ttl === 0) await client.set(key, value);
+      else await client.set(key, value, 'PX', ttl);
+    },
+
+    async delete(key) {
+      return await client.del(key) > 0;
+    },
+
+    async stop() {
+      if (!client) return;
+      const closing = client;
+      client = undefined;
+      // quit() rejects when the connection is already down; the socket still has
+      // to be released, or shutdown hangs on a Redis that died first.
+      await closing.quit().catch(() => closing.disconnect());
+    },
+  };
+}

package/cache/index.js

@@ -0,0 +1,155 @@
+import { noopLogger } from '../internal/logger.js';
+import { assertDuration, assertHandler, assertKey } from '../internal/validation.js';
+import { memoryStore } from './drivers/memory.js';
+import { redisStore } from './drivers/redis.js';
+
+const STORES = { memory: memoryStore, redis: redisStore };
+
+/**
+ * Creates a process-local or Redis-backed cache. Reads and writes degrade to a
+ * miss when the store fails; only `delete()` propagates, because a failed
+ * invalidation keeps serving stale data.
+ *
+ * @param {object} [options]
+ * @param {'memory'|'redis'} [options.driver='memory']
+ * @param {string} [options.redisUrl] - Required by the redis driver.
+ * @param {string} [options.prefix='app'] - Namespace every key is stored under.
+ * @param {number} [options.ttl=0] - Default lifetime in milliseconds; 0 never expires.
+ * @param {object} [options.logger]
+ * @return {object} The cache, not yet started; call start() first.
+ */
+export function createCache({
+  driver = 'memory',
+  redisUrl,
+  prefix = 'app',
+  ttl = 0,
+  logger = noopLogger,
+} = {}) {
+  const createStore = STORES[driver];
+  if (!createStore) {
+    throw new Error(`unknown cache driver "${driver}", expected ${Object.keys(STORES).join(' or ')}`);
+  }
+  const defaultTtl = assertDuration('ttl', ttl);
+  const store = createStore({ redisUrl, logger });
+  let state = 'idle';
+
+  function scope(key, action) {
+    if (state !== 'started') throw new Error(`the cache must be started before ${action}()`);
+    return `${prefix}:${assertKey(key)}`;
+  }
+
+  /**
+   * Reads a cached value.
+   *
+   * @param {string} key
+   * @return {Promise<*>} The stored value, or `undefined` on a miss.
+   */
+  async function get(key) {
+    const scoped = scope(key, 'get');
+    try {
+      const stored = await store.get(scoped);
+      return stored === undefined ? undefined : JSON.parse(stored);
+    } catch (error) {
+      logger.warn({ err: error, key: scoped }, 'cache read failed');
+      return undefined;
+    }
+  }
+
+  /**
+   * Whether a live entry exists, without transferring or parsing its value.
+   *
+   * @param {string} key
+   * @return {Promise<boolean>}
+   */
+  async function has(key) {
+    const scoped = scope(key, 'has');
+    try {
+      return await store.has(scoped);
+    } catch (error) {
+      logger.warn({ err: error, key: scoped }, 'cache read failed');
+      return false;
+    }
+  }
+
+  /**
+   * Stores a value, replacing any entry under the same key.
+   *
+   * @param {string} key
+   * @param {*} value - Must be JSON-serializable; `undefined` is how a miss is reported.
+   * @param {object} [options]
+   * @param {number} [options.ttl] - Overrides the cache default, in milliseconds.
+   * @return {Promise<void>}
+   */
+  async function set(key, value, { ttl: entryTtl = defaultTtl } = {}) {
+    const scoped = scope(key, 'set');
+    assertDuration('ttl', entryTtl);
+    // Both drivers store the serialized form, so a caller cannot mutate what the
+    // memory driver handed back and see the redis driver behave differently.
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+      throw new TypeError('a cache value must be JSON-serializable and not `undefined`');
+    }
+    try {
+      await store.set(scoped, serialized, entryTtl);
+    } catch (error) {
+      logger.warn({ err: error, key: scoped }, 'cache write failed');
+    }
+  }
+
+  /**
+   * Drops a cached value. Failures propagate: the caller decides what an
+   * invalidation that did not happen means for its request.
+   *
+   * @param {string} key
+   * @return {Promise<boolean>} True when an entry was removed.
+   */
+  async function remove(key) {
+    return store.delete(scope(key, 'delete'));
+  }
+
+  /**
+   * Reads a cached value, or produces it with `loader` and stores it.
+   *
+   * @param {string} key
+   * @param {() => (*|Promise<*>)} loader - Runs only on a miss; `undefined` is not cached.
+   * @param {object} [options]
+   * @param {number} [options.ttl] - Overrides the cache default, in milliseconds.
+   * @return {Promise<*>} The cached or freshly loaded value.
+   */
+  async function wrap(key, loader, { ttl: entryTtl = defaultTtl } = {}) {
+    scope(key, 'wrap');
+    assertHandler(key, loader);
+    const cached = await get(key);
+    if (cached !== undefined) return cached;
+    const value = await loader();
+    if (value !== undefined) await set(key, value, { ttl: entryTtl });
+    return value;
+  }
+
+  async function start() {
+    if (state === 'started') return;
+    if (state === 'stopped') throw new Error('a stopped cache cannot be restarted');
+    await store.start();
+    state = 'started';
+  }
+
+  async function stop() {
+    if (state === 'stopped') return;
+    await store.stop();
+    state = 'stopped';
+  }
+
+  return Object.freeze({
+    driver,
+    get,
+    has,
+    set,
+    delete: remove,
+    wrap,
+    start,
+    stop,
+    get state() {
+      return state;
+    },
+  });
+}

package/events/drivers/bullmq.js

@@ -1,8 +1,5 @@
-import {
-  loadBullmq,
-  queueName,
-  redisConnection,
-} from '../../internal/bullmq.js';
+import { loadBullmq, queueName } from '../../internal/bullmq.js';
+import { redisConnection } from '../../internal/redis.js';
 import { noopLogger } from '../../internal/logger.js';
 import { subscriberStream } from '../internal.js';
 

package/http/index.js

@@ -1,6 +1,7 @@
 export { createApp } from './createApp.js';
 export { default as decorators } from './plugins/decorators.js';
 export { default as errorHandler, classifyError, STATUS_BY_CODE } from './plugins/errorHandler.js';
+export { paginate } from './page.js';
 export { default as rawBody } from './plugins/rawBody.js';
 export { default as requestContext } from './plugins/requestContext.js';
 export {

package/http/page.js

@@ -0,0 +1,13 @@
+/**
+ * Shapes a page from rows fetched with `limit + 1` — the extra row is what reveals `hasMore`.
+ *
+ * @param {Array} rows - Up to `limit + 1` rows, in order.
+ * @param {number} limit - The page size the caller asked for.
+ * @param {number} [total] - Matching document count, when the resource exposes one.
+ * @return {{items: Array, hasMore: boolean, total?: number}} The page.
+ */
+export function paginate(rows, limit, total) {
+  const hasMore = rows.length > limit;
+  const items = hasMore ? rows.slice(0, limit) : rows;
+  return total === undefined ? { items, hasMore } : { items, hasMore, total };
+}

package/http/schema.js

@@ -9,6 +9,14 @@ export function pageQuery({ maxLimit = 100, defaultLimit = 20 } = {}) {
   });
 }
 
+export function pageResponse(items, { total = false } = {}) {
+  return objectSchema({
+    items: { type: 'array', items },
+    hasMore: { type: 'boolean' },
+    ...(total && { total: { type: 'integer', minimum: 0 } }),
+  }, total ? ['items', 'hasMore', 'total'] : ['items', 'hasMore']);
+}
+
 export const stringSchema = (options = {}) => ({ type: 'string', minLength: 1, ...options });
 export const email = Object.freeze({ type: 'string', format: 'email' });
 export const dateTime = Object.freeze({ type: 'string', format: 'date-time' });

package/internal/bullmq.js

@@ -14,32 +14,6 @@ export async function loadBullmq() {
   }
 }
 
-export function redisConnection(redisUrl, { worker = false } = {}) {
-  if (!redisUrl) throw new Error('a Redis connection requires `redisUrl`');
-  let url;
-  try {
-    url = new URL(redisUrl);
-  } catch (error) {
-    throw new Error(`invalid redisUrl: ${redisUrl}`, { cause: error });
-  }
-  if (!['redis:', 'rediss:'].includes(url.protocol)) {
-    throw new Error(`redisUrl must use redis:// or rediss://, got ${url.protocol}`);
-  }
-  const db = url.pathname.length > 1 ? Number(url.pathname.slice(1)) : 0;
-  if (!Number.isInteger(db) || db < 0) throw new Error(`invalid Redis database in ${redisUrl}`);
-
-  return {
-    host: url.hostname,
-    port: Number(url.port || 6379),
-    db,
-    ...(url.username ? { username: decodeURIComponent(url.username) } : {}),
-    ...(url.password ? { password: decodeURIComponent(url.password) } : {}),
-    ...(url.protocol === 'rediss:' ? { tls: {} } : {}),
-    // BullMQ workers refuse to start unless this is null; producers fail fast.
-    maxRetriesPerRequest: worker ? null : 1,
-  };
-}
-
 function safeSegment(value) {
   const source = String(value);
   // Slugifying is lossy; the hash suffix keeps the queue name unique.

package/internal/redis.js

@@ -0,0 +1,36 @@
+export async function loadIoredis() {
+  try {
+    return await import('ioredis');
+  } catch (error) {
+    if (['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'].includes(error?.code)) {
+      throw new Error('Redis support requires `ioredis`: install the package', { cause: error });
+    }
+    throw error;
+  }
+}
+
+export function redisConnection(redisUrl, { worker = false } = {}) {
+  if (!redisUrl) throw new Error('a Redis connection requires `redisUrl`');
+  let url;
+  try {
+    url = new URL(redisUrl);
+  } catch (error) {
+    throw new Error(`invalid redisUrl: ${redisUrl}`, { cause: error });
+  }
+  if (!['redis:', 'rediss:'].includes(url.protocol)) {
+    throw new Error(`redisUrl must use redis:// or rediss://, got ${url.protocol}`);
+  }
+  const db = url.pathname.length > 1 ? Number(url.pathname.slice(1)) : 0;
+  if (!Number.isInteger(db) || db < 0) throw new Error(`invalid Redis database in ${redisUrl}`);
+
+  return {
+    host: url.hostname,
+    port: Number(url.port || 6379),
+    db,
+    ...(url.username ? { username: decodeURIComponent(url.username) } : {}),
+    ...(url.password ? { password: decodeURIComponent(url.password) } : {}),
+    ...(url.protocol === 'rediss:' ? { tls: {} } : {}),
+    // BullMQ workers refuse to start unless this is null; producers fail fast.
+    maxRetriesPerRequest: worker ? null : 1,
+  };
+}

package/jobs/drivers/bullmq.js

@@ -1,8 +1,5 @@
-import {
-  loadBullmq,
-  queueName,
-  redisConnection,
-} from '../../internal/bullmq.js';
+import { loadBullmq, queueName } from '../../internal/bullmq.js';
+import { redisConnection } from '../../internal/redis.js';
 import { noopLogger } from '../../internal/logger.js';
 
 /**

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@devindex/api-kit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Building blocks for Fastify services: typed domain errors, HTTP plugins, logging and background runtime",
   "type": "module",
   "exports": {
+    "./cache": "./cache/index.js",
     "./context": "./context/index.js",
     "./env": "./env/index.js",
     "./errors": "./errors/index.js",
@@ -16,6 +17,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "cache",
     "context",
     "env",
     "errors",
@@ -50,7 +52,9 @@
     "schedule",
     "events",
     "event-bus",
-    "pubsub"
+    "pubsub",
+    "cache",
+    "redis"
   ],
   "peerDependencies": {
     "@fastify/cors": "^11.0.0",

package/schedule/drivers/bullmq.js

@@ -1,8 +1,5 @@
-import {
-  loadBullmq,
-  queueName,
-  redisConnection,
-} from '../../internal/bullmq.js';
+import { loadBullmq, queueName } from '../../internal/bullmq.js';
+import { redisConnection } from '../../internal/redis.js';
 import { noopLogger } from '../../internal/logger.js';
 
 const SCHEDULER_ID = 'schedule';