@beespoke/micro-server-redis 0.0.0-stage → 2.0.3

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @beespoke/micro-server-redis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared Redis connection lifecycle, application Redis subclasses, and query/index helpers.
+
+Supports Node 24+ and Bun 1.3.14+.
+
+## Install
+
+```sh
+npm install @beespoke/micro-server @beespoke/micro-server-redis
+```
+
+Use `bun add` in place of `npm install` for Bun projects.
+
+## Configure the plugin
+
+```ts
+import { defineConfig } from '@beespoke/micro-server';
+
+export default defineConfig({
+    plugins: ['@beespoke/micro-server-redis'],
+    pluginOptions: {
+        '@beespoke/micro-server-redis': {
+            url: process.env.REDIS_URL || 'redis://127.0.0.1:6379',
+        },
+    },
+});
+```
+
+Requires a running Redis server. Options use the native Redis client's shape, including `url`, `socket`, `username`, `password`, and `database`. Empty options retain the environment fallback. Redis search/index helpers additionally require a server supporting Redis Search commands.
+
+## Application connector
+
+The shared connection is available to subclasses of `BaseRedisConnector`:
+
+```ts
+import { BaseRedisConnector } from '@beespoke/micro-server-redis';
+
+class Cache extends BaseRedisConnector {
+    constructor() { super(); }
+
+    async ping() {
+        await this.ensureConnected();
+        return this.client.ping();
+    }
+}
+
+// After bootstrap, reuse the plugin's shared connection.
+const cache = new Cache();
+console.log(await cache.ping());
+```
+
+The base constructor and client accessor are protected. Standalone subclasses can pass native client options to `super(options)` and must call `disconnect()` when finished. The package also exports `BaseRedis` helpers, `parseQueryOptions`, `parseRediSearchQueryConfig`, and Redis client/search types.
+
+## Start the application
+
+Save the configuration as `micro-server.config.ts` next to your application's `package.json`, then create `index.ts`:
+
+```ts
+import { ApplicationServer } from '@beespoke/micro-server';
+
+await ApplicationServer.bootstrap();
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.once(signal, () => {
+        void ApplicationServer.close().catch(error => {
+            console.error(error);
+            process.exitCode = 1;
+        });
+    });
+}
+```
+
+Run `bun index.ts` or `node --env-file-if-exists=.env index.ts`. Node requires ESM (`"type": "module"` in package.json). When using Bun, load configuration secrets from the application environment or its `.env` file.
+
+## TypeScript and lifecycle
+
+Add this type-only import to an application-owned `plugin-types.d.ts` for configuration autocomplete:
+
+```ts
+import type {} from '@beespoke/micro-server-redis/plugin';
+```
+
+Core validates plugin options before setup and owns cleanup after successful startup or startup failure. Await `ApplicationServer.bootstrap()` before using the configured client, and call `ApplicationServer.close()` during application shutdown. Importing the package does not open a connection. Relative plugin paths resolve from the selected configuration file's directory.
+
+The root export can also be used without HTTP core. In that case, explicitly initialize and close the client. The `/plugin` entry is the integration adapter for `@beespoke/micro-server`.

package/dist/PluginContext.d.ts

@@ -0,0 +1,13 @@
+/** Structural subset of the core context; standalone clients need no HTTP dependency. */
+export interface Logger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+export interface PluginContext {
+    readonly logger: Logger;
+    readonly configDir: string;
+    onStart(hook: () => void | Promise<void>): void;
+    onClose(hook: () => void | Promise<void>): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './utils/BaseRedis/index.js';
+export { BaseRedisConnector } from './utils/BaseRedis/BaseRedisConnector.js';
+export { parseQueryOptions, parseRediSearchQueryConfig } from './utils/BaseRedis/RedisQueryHelper.js';
+export type { RedisClientOptions, RedisClientType, RediSearchSchema, FtSearchOptions } from 'redis';

package/dist/index.js

@@ -0,0 +1,697 @@
+// src/utils/BaseRedis/BaseRedisConnector.ts
+import { createClient } from "redis";
+
+class BaseRedisConnector {
+  options;
+  name = "redis";
+  static sharedClient = null;
+  static connectPromise = null;
+  static closePromise = null;
+  logger = console;
+  constructor(options) {
+    this.options = options;
+  }
+  get client() {
+    if (!BaseRedisConnector.sharedClient)
+      throw new Error("Redis is not connected; await ensureConnected() first");
+    return BaseRedisConnector.sharedClient;
+  }
+  async setup(context) {
+    this.logger = context.logger;
+    context.onClose(() => this.disconnect());
+    await this.ensureConnected();
+  }
+  connectionOptions() {
+    if (this.options)
+      return this.options;
+    const port = process.env.REDIS_PORT ? Number(process.env.REDIS_PORT) : undefined;
+    if (port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65535)) {
+      throw new Error("REDIS_PORT must be an integer between 1 and 65535");
+    }
+    const socket = {
+      ...process.env.REDIS_HOST ? { host: process.env.REDIS_HOST } : {},
+      ...port !== undefined ? { port } : {},
+      ...process.env.REDIS_TLS === "true" ? { tls: true } : {}
+    };
+    return {
+      url: process.env.REDIS_URL,
+      socket,
+      password: process.env.REDIS_PASS || process.env.REDIS_PASSWORD,
+      username: process.env.REDIS_USERNAME
+    };
+  }
+  async ensureConnected() {
+    if (BaseRedisConnector.closePromise)
+      await BaseRedisConnector.closePromise;
+    if (BaseRedisConnector.connectPromise)
+      return BaseRedisConnector.connectPromise;
+    if (BaseRedisConnector.sharedClient?.isOpen)
+      return;
+    const client = BaseRedisConnector.sharedClient ?? createClient(this.connectionOptions());
+    if (!BaseRedisConnector.sharedClient) {
+      BaseRedisConnector.sharedClient = client;
+      client.on("error", (error) => this.logger.error(error));
+    }
+    BaseRedisConnector.connectPromise = (async () => {
+      try {
+        await client.connect();
+      } catch (error) {
+        try {
+          if (client.isOpen)
+            client.destroy();
+        } catch (cleanupError) {
+          throw new AggregateError([error, cleanupError], "Redis connection and cleanup failed", { cause: error });
+        } finally {
+          if (BaseRedisConnector.sharedClient === client)
+            BaseRedisConnector.sharedClient = null;
+        }
+        throw error;
+      }
+    })();
+    try {
+      await BaseRedisConnector.connectPromise;
+    } finally {
+      BaseRedisConnector.connectPromise = null;
+    }
+  }
+  async disconnect() {
+    if (BaseRedisConnector.closePromise)
+      return BaseRedisConnector.closePromise;
+    const client = BaseRedisConnector.sharedClient;
+    if (!client)
+      return;
+    BaseRedisConnector.closePromise = (async () => {
+      const errors = [];
+      try {
+        if (client.isOpen) {
+          if (client.isReady)
+            await client.quit();
+          else
+            client.destroy();
+        }
+      } catch (error) {
+        errors.push(error);
+        try {
+          if (client.isOpen)
+            client.destroy();
+        } catch (cleanupError) {
+          errors.push(cleanupError);
+        }
+      }
+      try {
+        await BaseRedisConnector.connectPromise;
+      } catch {}
+      if (BaseRedisConnector.sharedClient === client)
+        BaseRedisConnector.sharedClient = null;
+      BaseRedisConnector.connectPromise = null;
+      if (errors.length)
+        throw new AggregateError(errors, "Failed to close Redis connection");
+    })();
+    try {
+      await BaseRedisConnector.closePromise;
+    } finally {
+      BaseRedisConnector.closePromise = null;
+    }
+  }
+}
+
+// src/utils/BaseRedis/BaseRedisCore.ts
+class BaseRedisCore extends BaseRedisConnector {
+  constructor(options) {
+    super(options);
+  }
+  ready = async () => {
+    await this.ensureConnected();
+    return this.client;
+  };
+  chunk(arr, size) {
+    const result = [];
+    for (let i = 0;i < arr.length; i += size) {
+      result.push(arr.slice(i, i + size));
+    }
+    return result;
+  }
+  normalizeSearchFields(fields) {
+    if (!fields)
+      return {};
+    const normalized = {};
+    for (const [key, value] of Object.entries(fields)) {
+      if (value == null)
+        continue;
+      if (value instanceof Date) {
+        normalized[key] = value.getTime().toString();
+        continue;
+      }
+      if (Array.isArray(value)) {
+        normalized[key] = value.map((item) => `${item}`).join(",");
+        continue;
+      }
+      if (typeof value === "object") {
+        normalized[key] = JSON.stringify(value);
+        continue;
+      }
+      normalized[key] = `${value}`;
+    }
+    return normalized;
+  }
+  parseSort(sort) {
+    const [field = "createdAt", dir = "desc"] = (sort ?? "").split(":");
+    return {
+      field,
+      direction: dir.toLowerCase() === "asc" ? "ASC" : "DESC"
+    };
+  }
+  parseHashRow(data) {
+    if (!data || data.data == null)
+      return null;
+    let parsed;
+    if (typeof data.data === "string") {
+      try {
+        parsed = JSON.parse(data.data);
+      } catch {
+        return null;
+      }
+    } else if (typeof data.data === "object") {
+      parsed = data.data;
+    } else {
+      return null;
+    }
+    let updatedAt;
+    if (data.updatedAt != null) {
+      const num = Number(data.updatedAt);
+      updatedAt = Number.isFinite(num) ? new Date(num) : new Date(`${data.updatedAt}`);
+    }
+    return {
+      ...parsed,
+      updatedAt
+    };
+  }
+  resolveDocKey(docId, itemPrefix) {
+    if (!itemPrefix)
+      return docId;
+    return docId.includes(":") ? docId : `${itemPrefix}:${docId}`;
+  }
+  inferPrefixFromKey(key) {
+    const idx = key.lastIndexOf(":");
+    return idx > 0 ? key.slice(0, idx) : undefined;
+  }
+  resolveIndexId(id, itemPrefix) {
+    if (itemPrefix && id.startsWith(`${itemPrefix}:`)) {
+      return id.slice(itemPrefix.length + 1);
+    }
+    return id;
+  }
+  buildHashPayload(item, updatedAt, extraFields) {
+    const normalized = this.normalizeSearchFields(extraFields);
+    delete normalized.data;
+    delete normalized.updatedAt;
+    return {
+      data: JSON.stringify(item),
+      updatedAt: updatedAt.toString(),
+      ...normalized
+    };
+  }
+}
+// src/utils/BaseRedis/BaseRedisIndexing.ts
+class BaseRedisIndexing extends BaseRedisCore {
+  static ensuredSearchIndexes = new WeakMap;
+  ensureSearchIndex = async (params) => {
+    const client = await this.ready();
+    let ensured = BaseRedisIndexing.ensuredSearchIndexes.get(client);
+    if (!ensured) {
+      ensured = new Set;
+      BaseRedisIndexing.ensuredSearchIndexes.set(client, ensured);
+    }
+    if (ensured.has(params.indexKey))
+      return;
+    try {
+      await client.ft.create(params.indexKey, params.schema, params.options);
+    } catch (error) {
+      const message = typeof error?.message === "string" ? error.message.toLowerCase() : "";
+      if (!message.includes("index already exists")) {
+        throw error;
+      }
+    }
+    ensured.add(params.indexKey);
+  };
+  syncIndexedCollection = async (params) => {
+    const {
+      items,
+      idSelector,
+      scoreSelector,
+      indexKey,
+      itemPrefix,
+      maxItems,
+      ttlSeconds,
+      batchSize = 500,
+      search
+    } = params;
+    const client = await this.ready();
+    if (search) {
+      await this.syncFTIndex(search, itemPrefix);
+    }
+    if (!items.length)
+      return;
+    const now = Date.now();
+    const entries = items.map((item) => {
+      const id = idSelector(item);
+      const rawScore = scoreSelector(item);
+      const score = rawScore instanceof Date ? rawScore.getTime() : Number(rawScore ?? now);
+      return { id: `${id}`, score, item };
+    });
+    const pipeline = client.multi();
+    pipeline.zAdd(indexKey, entries.map((e) => ({ value: e.id, score: e.score })));
+    if (ttlSeconds) {
+      pipeline.expire(indexKey, ttlSeconds);
+    }
+    for (const { id, item, score } of entries) {
+      const key = `${itemPrefix}:${id}`;
+      const extraFields = search?.fields ? this.normalizeSearchFields(search.fields(item, score)) : {};
+      delete extraFields.data;
+      delete extraFields.updatedAt;
+      pipeline.hSet(key, {
+        data: JSON.stringify(item),
+        updatedAt: now.toString(),
+        ...extraFields
+      });
+      if (ttlSeconds) {
+        pipeline.expire(key, ttlSeconds);
+      }
+    }
+    await pipeline.exec();
+    const total = await client.zCard(indexKey);
+    if (total > maxItems) {
+      const overflow = total - maxItems;
+      const script = `
+                local overflow = tonumber(ARGV[1])
+                if overflow <= 0 then return {} end
+                local ids = redis.call('zrange', KEYS[1], 0, overflow - 1)
+                if #ids > 0 then
+                    redis.call('zremrangebyrank', KEYS[1], 0, overflow - 1)
+                end
+                return ids
+            `;
+      const evicted = await client.eval(script, {
+        keys: [indexKey],
+        arguments: [String(overflow)]
+      });
+      if (Array.isArray(evicted) && evicted.length) {
+        for (const chunk of this.chunk(evicted, batchSize)) {
+          const delPipe = client.multi();
+          for (const id of chunk) {
+            delPipe.unlink(`${itemPrefix}:${id}`);
+          }
+          await delPipe.exec();
+        }
+      }
+    }
+  };
+  searchIndexedItems = async (params) => {
+    const {
+      search,
+      itemPrefix,
+      options = {},
+      maxLimit
+    } = params;
+    const client = await this.ready();
+    const paginate = options.paginate ?? true;
+    const hardCap = Math.max(1, maxLimit ?? 100);
+    const limit = paginate ? Math.min(100, Math.max(1, options.limit ?? 20)) : hardCap;
+    const rawPage = Math.max(1, options.page ?? 1);
+    const shouldCount = (options.withCount ?? false) || paginate;
+    const rawQuery = typeof search.query === "string" ? search.query : options.search ?? "*";
+    const query = rawQuery.trim().length ? rawQuery.trim() : "*";
+    const sortInfo = this.parseSort(options.sort ?? "createdAt:desc");
+    const explicitSort = search.sortBy && search.sortBy.includes(":") ? this.parseSort(search.sortBy) : null;
+    const sortByField = explicitSort ? explicitSort.field : search.sortBy;
+    const sortDirection = explicitSort ? explicitSort.direction : sortInfo.direction;
+    const buildSearchOptions = (from) => {
+      const searchOptions = {
+        LIMIT: { from, size: limit }
+      };
+      const returnFields = search.returnFields ?? ["data", "updatedAt"];
+      if (returnFields.length > 0) {
+        searchOptions.RETURN = returnFields;
+      }
+      if (sortByField) {
+        searchOptions.SORTBY = {
+          BY: sortByField,
+          DIRECTION: sortDirection
+        };
+      }
+      if (search.dialect != null) {
+        searchOptions.DIALECT = search.dialect;
+      }
+      return searchOptions;
+    };
+    let page = paginate ? rawPage : 1;
+    let offset = (page - 1) * limit;
+    let result = await client.ft.search(search.indexKey, query, buildSearchOptions(offset));
+    const total = result.total ?? 0;
+    if (total === 0) {
+      return {
+        rows: [],
+        count: shouldCount ? 0 : undefined,
+        page: 1,
+        limit,
+        hasNextPage: false
+      };
+    }
+    if (paginate) {
+      const totalPages = Math.max(1, Math.ceil(total / limit));
+      const clampedPage = Math.min(page, totalPages);
+      if (clampedPage !== page) {
+        page = clampedPage;
+        offset = (page - 1) * limit;
+        result = await client.ft.search(search.indexKey, query, buildSearchOptions(offset));
+      }
+    }
+    const rowsById = new Map;
+    const missingKeys = [];
+    result.documents.forEach((doc) => {
+      const row = this.parseHashRow(doc.value);
+      if (row) {
+        rowsById.set(doc.id, row);
+      } else {
+        missingKeys.push(doc.id);
+      }
+    });
+    if (missingKeys.length) {
+      const pipeline = client.multi();
+      for (const docId of missingKeys) {
+        pipeline.hGetAll(this.resolveDocKey(docId, itemPrefix));
+      }
+      const raw = await pipeline.exec();
+      raw?.forEach((data, index) => {
+        const row = this.parseHashRow(data);
+        if (row) {
+          rowsById.set(missingKeys[index], row);
+        }
+      });
+    }
+    const rows = result.documents.map((doc) => rowsById.get(doc.id)).filter(Boolean);
+    const hasNextPage = paginate ? offset + limit < total : false;
+    return {
+      rows,
+      count: shouldCount ? total : undefined,
+      page,
+      limit,
+      hasNextPage
+    };
+  };
+  getIndexedItems = async (params) => {
+    const {
+      indexKey,
+      itemPrefix,
+      options = {},
+      maxLimit,
+      search
+    } = params;
+    const rawQuery = typeof search?.query === "string" ? search.query : options.search;
+    if (search?.indexKey && typeof rawQuery === "string" && rawQuery.trim().length > 0) {
+      return this.searchIndexedItems({
+        search: {
+          ...search,
+          query: rawQuery
+        },
+        itemPrefix,
+        options,
+        maxLimit
+      });
+    }
+    const client = await this.ready();
+    const paginate = options.paginate ?? true;
+    const hardCap = Math.max(1, maxLimit ?? 100);
+    const limit = paginate ? Math.min(100, Math.max(1, options.limit ?? 20)) : hardCap;
+    const rawPage = Math.max(1, options.page ?? 1);
+    const sort = options.sort ?? "createdAt:desc";
+    const withCount = options.withCount ?? false;
+    const shouldCount = withCount || paginate;
+    let count;
+    if (shouldCount) {
+      count = await client.zCard(indexKey);
+      if (!count) {
+        return {
+          rows: [],
+          count: 0,
+          page: 1,
+          limit,
+          hasNextPage: false
+        };
+      }
+    }
+    const totalPages = paginate && count != null ? Math.max(1, Math.ceil(count / limit)) : 1;
+    const page = paginate ? count != null ? Math.min(rawPage, totalPages) : rawPage : 1;
+    const start = (page - 1) * limit;
+    const stop = start + limit - 1;
+    const isDesc = sort.endsWith(":desc");
+    const ids = await client.zRange(indexKey, start, stop, { REV: isDesc });
+    if (!ids.length) {
+      return {
+        rows: [],
+        count,
+        page,
+        limit,
+        hasNextPage: false
+      };
+    }
+    const pipeline = client.multi();
+    for (const id of ids) {
+      pipeline.hGetAll(`${itemPrefix}:${id}`);
+    }
+    const raw = await pipeline.exec();
+    const rows = [];
+    raw?.forEach((data) => {
+      const row = this.parseHashRow(data);
+      if (row) {
+        rows.push(row);
+      }
+    });
+    let hasNextPage = false;
+    if (paginate) {
+      if (count != null) {
+        hasNextPage = start + limit < count;
+      } else {
+        hasNextPage = ids.length === limit;
+      }
+    }
+    return {
+      rows,
+      count,
+      page,
+      limit,
+      hasNextPage
+    };
+  };
+  async syncFTIndex(config, itemPrefix) {
+    const createOptions = {
+      ...config.options ?? {}
+    };
+    if (!createOptions.ON) {
+      createOptions.ON = "HASH";
+    }
+    if (!createOptions.PREFIX) {
+      createOptions.PREFIX = `${itemPrefix}:`;
+    }
+    await this.ensureSearchIndex({
+      indexKey: config.indexKey,
+      schema: config.schema,
+      options: createOptions
+    });
+  }
+}
+// src/utils/BaseRedis/BaseRedisCrud.ts
+class BaseRedisCrud extends BaseRedisIndexing {
+  constructor(options) {
+    super(options);
+  }
+  find = async (params) => {
+    return this.getIndexedItems(params);
+  };
+  findById = async (params) => {
+    const client = await this.ready();
+    const docId = `${params.id}`;
+    const key = this.resolveDocKey(docId, params.itemPrefix);
+    const data = await client.hGetAll(key);
+    if (!data || Object.keys(data).length === 0)
+      return null;
+    return this.parseHashRow(data);
+  };
+  insert = async (params) => {
+    const {
+      id,
+      item,
+      itemPrefix,
+      ttlSeconds,
+      indexKey,
+      score,
+      scoreSelector,
+      search
+    } = params;
+    const client = await this.ready();
+    const docId = `${id}`;
+    const inferredPrefix = itemPrefix ?? this.inferPrefixFromKey(docId);
+    const indexId = this.resolveIndexId(docId, inferredPrefix);
+    const now = Date.now();
+    if (search) {
+      if (!inferredPrefix) {
+        throw new Error("itemPrefix is required when using search indexing.");
+      }
+      await this.syncFTIndex(search, inferredPrefix);
+    }
+    const rawScore = scoreSelector ? scoreSelector(item) : score;
+    const scoreValue = rawScore instanceof Date ? rawScore.getTime() : Number(rawScore ?? now);
+    const normalizedScore = Number.isFinite(scoreValue) ? scoreValue : now;
+    const extraFields = search?.fields ? search.fields(item, normalizedScore) : undefined;
+    const payload = this.buildHashPayload(item, now, extraFields);
+    const key = this.resolveDocKey(docId, inferredPrefix);
+    const pipeline = client.multi();
+    if (indexKey) {
+      pipeline.zAdd(indexKey, [{ value: indexId, score: normalizedScore }]);
+      if (ttlSeconds) {
+        pipeline.expire(indexKey, ttlSeconds);
+      }
+    }
+    pipeline.hSet(key, payload);
+    if (ttlSeconds) {
+      pipeline.expire(key, ttlSeconds);
+    }
+    await pipeline.exec();
+    return item;
+  };
+  update = async (params) => {
+    const {
+      id,
+      updates,
+      replace = false,
+      itemPrefix,
+      ttlSeconds,
+      indexKey,
+      score,
+      scoreSelector,
+      search
+    } = params;
+    const current = await this.findById({ id, itemPrefix });
+    if (!current)
+      return null;
+    const patch = typeof updates === "function" ? updates(current) : updates;
+    const next = replace ? patch : { ...current, ...patch };
+    const client = await this.ready();
+    const docId = `${id}`;
+    const inferredPrefix = itemPrefix ?? this.inferPrefixFromKey(docId);
+    const indexId = this.resolveIndexId(docId, inferredPrefix);
+    const now = Date.now();
+    if (search) {
+      if (!inferredPrefix) {
+        throw new Error("itemPrefix is required when using search indexing.");
+      }
+      await this.syncFTIndex(search, inferredPrefix);
+    }
+    const rawScore = scoreSelector ? scoreSelector(next) : score;
+    const scoreValue = rawScore instanceof Date ? rawScore.getTime() : rawScore != null ? Number(rawScore) : undefined;
+    const normalizedScore = scoreValue != null && Number.isFinite(scoreValue) ? scoreValue : now;
+    const extraFields = search?.fields ? search.fields(next, normalizedScore) : undefined;
+    const payload = this.buildHashPayload(next, now, extraFields);
+    const key = this.resolveDocKey(docId, inferredPrefix);
+    const pipeline = client.multi();
+    pipeline.hSet(key, payload);
+    if (ttlSeconds) {
+      pipeline.expire(key, ttlSeconds);
+    }
+    if (indexKey && rawScore != null) {
+      pipeline.zAdd(indexKey, [{ value: indexId, score: normalizedScore }]);
+      if (ttlSeconds) {
+        pipeline.expire(indexKey, ttlSeconds);
+      }
+    }
+    await pipeline.exec();
+    return next;
+  };
+  delete = async (params) => {
+    const { id, itemPrefix, indexKey } = params;
+    const client = await this.ready();
+    const docId = `${id}`;
+    const inferredPrefix = itemPrefix ?? this.inferPrefixFromKey(docId);
+    const indexId = this.resolveIndexId(docId, inferredPrefix);
+    const key = this.resolveDocKey(docId, inferredPrefix);
+    const pipeline = client.multi();
+    pipeline.unlink(key);
+    if (indexKey) {
+      pipeline.zRem(indexKey, indexId);
+    }
+    const result = await pipeline.exec();
+    const removed = Array.isArray(result) && typeof result[0] === "number" ? result[0] : 0;
+    return removed > 0;
+  };
+}
+// src/utils/BaseRedis/RedisQueryHelper.ts
+var toNumber = (value) => {
+  if (typeof value === "string") {
+    const n = Number(value);
+    return Number.isNaN(n) ? undefined : n;
+  }
+  return;
+};
+var toBoolean = (value) => {
+  if (typeof value === "string") {
+    if (value === "true")
+      return true;
+    if (value === "false")
+      return false;
+  }
+  return;
+};
+var toString = (value) => {
+  if (typeof value === "string")
+    return value;
+  return;
+};
+var toStringArray = (value) => {
+  if (typeof value === "string") {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => typeof item === "string" ? item : []);
+  }
+  return;
+};
+function parseQueryOptions(query) {
+  const page = toNumber(query.page);
+  const limit = toNumber(query.limit);
+  const search = toString(query.search);
+  return {
+    page: page && page > 0 ? page : undefined,
+    limit: limit && limit > 0 ? limit : undefined,
+    sort: toString(query.sort),
+    withCount: toBoolean(query.withCount),
+    paginate: toBoolean(query.paginate),
+    search
+  };
+}
+function parseRediSearchQueryConfig(query, config) {
+  const source = query;
+  const searchKey = config.searchParam ?? "search";
+  const sortByKey = config.sortByParam ?? "sortBy";
+  const returnFieldsKey = config.returnFieldsParam ?? "returnFields";
+  const dialectKey = config.dialectParam ?? "dialect";
+  const search = toString(source[searchKey]);
+  const sortBy = toString(source[sortByKey]) ?? config.defaultSortBy;
+  const returnFields = toStringArray(source[returnFieldsKey]) ?? config.defaultReturnFields;
+  const dialect = toNumber(source[dialectKey]) ?? config.defaultDialect;
+  return {
+    indexKey: config.indexKey,
+    query: search,
+    sortBy,
+    returnFields,
+    dialect
+  };
+}
+export {
+  parseRediSearchQueryConfig,
+  parseQueryOptions,
+  BaseRedisIndexing,
+  BaseRedisCrud,
+  BaseRedisCore,
+  BaseRedisConnector,
+  BaseRedisCrud as BaseRedis
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,10 @@
+import type { PluginDefinition } from '@beespoke/micro-server';
+import { type RedisClientOptions } from '../index.js';
+export type RedisPluginOptions = RedisClientOptions;
+declare module '@beespoke/micro-server' {
+    interface PluginOptionsRegistry {
+        '@beespoke/micro-server-redis': RedisPluginOptions;
+    }
+}
+declare const definition: PluginDefinition<RedisPluginOptions>;
+export default definition;

package/dist/plugin/index.js

@@ -0,0 +1,115 @@
+// src/plugin/index.ts
+import { BaseRedisConnector } from "../index.js";
+
+class RedisPlugin extends BaseRedisConnector {
+  constructor(options) {
+    super(options);
+  }
+}
+function object(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function validateUrl(value) {
+  try {
+    if (typeof value !== "string")
+      throw new Error;
+    const url = new URL(value);
+    if (!["redis:", "rediss:"].includes(url.protocol) || !url.hostname)
+      throw new Error;
+    if (url.pathname && url.pathname !== "/" && !/^\/\d+$/.test(url.pathname))
+      throw new Error;
+  } catch {
+    throw new Error("Redis url must be a redis or rediss URL with an optional nonnegative database number");
+  }
+}
+var definition = {
+  name: "@beespoke/micro-server-redis",
+  validate(options) {
+    if (!object(options))
+      throw new Error("Redis options must be an object");
+    const keys = [
+      "url",
+      "socket",
+      "username",
+      "password",
+      "credentialsProvider",
+      "name",
+      "database",
+      "commandsQueueMaxLength",
+      "disableOfflineQueue",
+      "readonly",
+      "pingInterval",
+      "commandOptions",
+      "clientSideCache",
+      "disableClientInfo",
+      "clientInfoTag",
+      "emitInvalidate",
+      "maintNotifications",
+      "maintEndpointType",
+      "maintRelaxedCommandTimeout",
+      "maintRelaxedSocketTimeout",
+      "modules",
+      "functions",
+      "scripts",
+      "RESP",
+      "unstableResp3"
+    ];
+    if (Object.keys(options).some((key) => !keys.includes(key)))
+      throw new Error("Redis options contain an unknown field");
+    if (options.url !== undefined)
+      validateUrl(options.url);
+    for (const key of ["username", "password", "name", "clientInfoTag"]) {
+      if (options[key] !== undefined && typeof options[key] !== "string")
+        throw new Error(`Redis ${key} must be a string`);
+    }
+    for (const key of ["database", "commandsQueueMaxLength", "pingInterval", "maintRelaxedCommandTimeout", "maintRelaxedSocketTimeout"]) {
+      if (options[key] !== undefined && (!Number.isSafeInteger(options[key]) || options[key] < 0))
+        throw new Error(`Redis ${key} must be a nonnegative integer`);
+    }
+    for (const key of ["disableOfflineQueue", "readonly", "disableClientInfo", "emitInvalidate", "unstableResp3"]) {
+      if (options[key] !== undefined && typeof options[key] !== "boolean")
+        throw new Error(`Redis ${key} must be a boolean`);
+    }
+    if (options.RESP !== undefined && options.RESP !== 2 && options.RESP !== 3)
+      throw new Error("Redis RESP must be 2 or 3");
+    for (const key of ["credentialsProvider", "commandOptions", "clientSideCache", "modules", "functions", "scripts"]) {
+      if (options[key] !== undefined && !object(options[key]))
+        throw new Error(`Redis ${key} must be an object`);
+    }
+    if (options.socket !== undefined) {
+      const socket = options.socket;
+      if (!object(socket))
+        throw new Error("Redis socket must be an object");
+      if (socket.port !== undefined && (!Number.isInteger(socket.port) || socket.port < 1 || socket.port > 65535))
+        throw new Error("Redis socket.port must be an integer between 1 and 65535");
+      for (const key of ["host", "path"]) {
+        if (socket[key] !== undefined && (typeof socket[key] !== "string" || !socket[key].trim()))
+          throw new Error(`Redis socket.${key} must be a nonempty string`);
+      }
+      if (socket.tls !== undefined && typeof socket.tls !== "boolean")
+        throw new Error("Redis socket.tls must be a boolean");
+      for (const key of ["connectTimeout", "socketTimeout"]) {
+        if (socket[key] !== undefined && (typeof socket[key] !== "number" || !Number.isFinite(socket[key]) || socket[key] < 0))
+          throw new Error(`Redis socket.${key} must be a nonnegative number`);
+      }
+      if (socket.reconnectStrategy !== undefined && socket.reconnectStrategy !== false && typeof socket.reconnectStrategy !== "function" && (typeof socket.reconnectStrategy !== "number" || !Number.isFinite(socket.reconnectStrategy) || socket.reconnectStrategy < 0))
+        throw new Error("Redis socket.reconnectStrategy must be false, a nonnegative number or a function");
+    }
+    if (!Object.keys(options).length) {
+      if (process.env.REDIS_URL)
+        validateUrl(process.env.REDIS_URL);
+      if (process.env.REDIS_PORT !== undefined) {
+        const port = Number(process.env.REDIS_PORT);
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+          throw new Error("Redis REDIS_PORT must be an integer between 1 and 65535");
+      }
+    }
+  },
+  create(options) {
+    return new RedisPlugin(Object.keys(options).length ? options : undefined);
+  }
+};
+var plugin_default = definition;
+export {
+  plugin_default as default
+};

package/dist/types/RedisTypes.d.ts

@@ -0,0 +1,47 @@
+import type { RediSearchSchema } from "redis";
+export interface QueryOptions {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    withCount?: boolean;
+    paginate?: boolean;
+    search?: string;
+}
+export type RediSearchFieldValue = string | number | boolean | Date | null | undefined | Array<string | number | boolean>;
+export interface RediSearchCreateOptions {
+    ON?: "HASH" | "JSON";
+    PREFIX?: string | string[];
+    FILTER?: string;
+    LANGUAGE?: string;
+    LANGUAGE_FIELD?: string;
+    SCORE?: number;
+    SCORE_FIELD?: string;
+    MAXTEXTFIELDS?: boolean;
+    TEMPORARY?: number;
+    NOOFFSETS?: boolean;
+    NOHL?: boolean;
+    NOFIELDS?: boolean;
+    NOFREQS?: boolean;
+    SKIPINITIALSCAN?: boolean;
+    STOPWORDS?: string[] | "OFF";
+}
+export interface RediSearchIndexConfig<T = unknown> {
+    indexKey: string;
+    schema: RediSearchSchema;
+    options?: RediSearchCreateOptions;
+    fields?: (item: T, score: number) => Record<string, RediSearchFieldValue>;
+}
+export interface RediSearchQueryConfig {
+    indexKey: string;
+    query?: string;
+    sortBy?: string;
+    returnFields?: string[];
+    dialect?: number;
+}
+export interface RedisResult<T> {
+    rows: T[];
+    count?: number;
+    page: number;
+    limit: number;
+    hasNextPage: boolean;
+}

package/dist/utils/BaseRedis/BaseRedisConnector.d.ts

@@ -0,0 +1,17 @@
+import { type RedisClientOptions, type RedisClientType } from 'redis';
+import type { PluginContext, Logger } from '../../PluginContext.js';
+/** Shared client facade. Constructors are inert; setup/ensureConnected opens the connection. */
+export declare class BaseRedisConnector {
+    private readonly options?;
+    readonly name = "redis";
+    private static sharedClient;
+    private static connectPromise;
+    private static closePromise;
+    protected logger: Logger;
+    protected constructor(options?: RedisClientOptions);
+    protected get client(): RedisClientType;
+    setup(context: PluginContext): Promise<void>;
+    private connectionOptions;
+    ensureConnected(): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/dist/utils/BaseRedis/BaseRedisCore.d.ts

@@ -0,0 +1,79 @@
+import type { RedisClientType, RedisClientOptions } from "redis";
+import { BaseRedisConnector } from "./BaseRedisConnector.js";
+import type { RediSearchFieldValue } from "../../types/RedisTypes.js";
+/**
+ * Core Redis utility class providing common helpers for working with Redis,
+ * including connection handling, data normalization, key resolution, and hash building.
+ * Intended to be extended by specialized Redis managers.
+ */
+export declare class BaseRedisCore extends BaseRedisConnector {
+    /** Protected constructor; use by extending classes. */
+    protected constructor(options?: RedisClientOptions);
+    /**
+     * Ensures the Redis client is connected and ready.
+     * The connector shares in-flight connections and supports reconnecting after close.
+     * @returns {Promise<RedisClientType>} Connected Redis client.
+     */
+    protected ready: () => Promise<RedisClientType>;
+    /**
+     * Splits an array into chunks of a given size.
+     * Useful for batching Redis operations.
+     * @param arr Array of items to split
+     * @param size Maximum size of each chunk
+     * @returns Array of chunks
+     */
+    protected chunk<T>(arr: T[], size: number): T[][];
+    /**
+     * Normalizes Redis field values to strings.
+     * Converts Dates, Arrays, and Objects; skips null/undefined.
+     * @param fields Optional record of fields
+     * @returns Normalized record with string values
+     */
+    protected normalizeSearchFields(fields?: Record<string, RediSearchFieldValue>): Record<string, string>;
+    /**
+     * Parses a sort string into a field and direction.
+     * @param sort Sort string in the format "field:asc" or "field:desc"
+     * @returns Object containing field and direction ("ASC" or "DESC")
+     */
+    protected parseSort(sort?: string): {
+        field: string;
+        direction: "ASC" | "DESC";
+    };
+    /**
+     * Parses a Redis hash row into a typed object.
+     * Converts `data` JSON string to object and parses `updatedAt` to Date.
+     * @param data Redis hash row with `data` and `updatedAt` keys
+     * @returns Parsed object of type T or null if invalid
+     */
+    protected parseHashRow<T>(data: Record<string, any>): T | null;
+    /**
+     * Resolves a document key by adding an optional prefix.
+     * @param docId Document ID
+     * @param itemPrefix Optional prefix to namespace keys
+     * @returns Full Redis key
+     */
+    protected resolveDocKey(docId: string, itemPrefix?: string): string;
+    /**
+     * Infers the prefix from a Redis key.
+     * @param key Redis key (e.g., "feed:123")
+     * @returns Prefix string or undefined if none found
+     */
+    protected inferPrefixFromKey(key: string): string | undefined;
+    /**
+     * Resolves the actual ID by removing the prefix if present.
+     * @param id Redis key or ID
+     * @param itemPrefix Optional prefix to remove
+     * @returns ID without prefix
+     */
+    protected resolveIndexId(id: string, itemPrefix?: string): string;
+    /**
+     * Builds a Redis hash payload for storing an object.
+     * Includes `data`, `updatedAt`, and optional extra fields.
+     * Reserved keys `data` and `updatedAt` in extraFields are ignored.
+     * @param item Object to store
+     * @param updatedAt Timestamp in milliseconds
+     * @param extraFields Optional extra fields for Redis
+     * @returns Redis hash payload with string values
+     */
+    protected buildHashPayload<T>(item: T, updatedAt: number, extraFields?: Record<string, RediSearchFieldValue>): Record<string, string>;
+}

package/dist/utils/BaseRedis/BaseRedisCrud.d.ts

@@ -0,0 +1,84 @@
+import type { QueryOptions, RediSearchIndexConfig, RediSearchQueryConfig, RedisResult } from "../../types/RedisTypes.js";
+import { BaseRedisIndexing } from "./BaseRedisIndexing.js";
+import type { RedisClientOptions } from 'redis';
+/**
+ * BaseRedisCrud
+ *
+ * Provides CRUD (Create, Read, Update, Delete) operations on Redis
+ * with optional search indexing support.
+ * Extends `BaseRedisIndexing` for full-text search and indexing utilities.
+ */
+export declare class BaseRedisCrud extends BaseRedisIndexing {
+    /**
+     * Protected constructor. Use by extending classes.
+     */
+    protected constructor(options?: RedisClientOptions);
+    /**
+     * Find multiple items in a Redis index with optional search and query options.
+     * @template T - Type of the stored objects
+     * @param params Index key, item prefix, query options, maxLimit, and search config
+     * @returns Promise resolving to RedisResult containing matching items
+     */
+    protected find: <T>(params: {
+        indexKey: string;
+        itemPrefix: string;
+        options?: QueryOptions;
+        maxLimit?: number;
+        search?: RediSearchQueryConfig;
+    }) => Promise<RedisResult<T>>;
+    /**
+     * Find a single item by ID.
+     * @template T - Type of the stored object
+     * @param params ID and optional itemPrefix
+     * @returns Promise resolving to the object or null if not found
+     */
+    protected findById: <T>(params: {
+        id: string | number;
+        itemPrefix?: string;
+    }) => Promise<T | null>;
+    /**
+     * Insert a new item into Redis with optional TTL, indexing, and score.
+     * @template T - Type of the stored object
+     * @param params Object containing id, item, itemPrefix, TTL, index info, score, and search config
+     * @returns Promise resolving to the inserted item
+     */
+    protected insert: <T>(params: {
+        id: string | number;
+        item: T;
+        itemPrefix?: string;
+        ttlSeconds?: number;
+        indexKey?: string;
+        score?: number | Date;
+        scoreSelector?: (item: T) => number | Date;
+        search?: RediSearchIndexConfig<T>;
+    }) => Promise<T>;
+    /**
+     * Update an existing item by ID with partial updates or full replacement.
+     * Updates the index score if provided.
+     * @template T - Type of the stored object
+     * @param params Object containing id, updates (partial or function), replace flag, TTL, index info, score, and search config
+     * @returns Promise resolving to updated object or null if item does not exist
+     */
+    protected update: <T>(params: {
+        id: string | number;
+        updates: Partial<T> | ((current: T) => Partial<T> | T);
+        replace?: boolean;
+        itemPrefix?: string;
+        ttlSeconds?: number;
+        indexKey?: string;
+        score?: number | Date;
+        scoreSelector?: (item: T) => number | Date;
+        search?: RediSearchIndexConfig<T>;
+    }) => Promise<T | null>;
+    /**
+     * Delete an item by ID.
+     * Removes the Redis hash and optionally removes the item from the index.
+     * @param params Object containing id, optional itemPrefix, and optional indexKey
+     * @returns Promise resolving to true if item was removed, false otherwise
+     */
+    protected delete: (params: {
+        id: string | number;
+        itemPrefix?: string;
+        indexKey?: string;
+    }) => Promise<boolean>;
+}

package/dist/utils/BaseRedis/BaseRedisIndexing.d.ts

@@ -0,0 +1,75 @@
+import type { RediSearchSchema } from "redis";
+import { BaseRedisCore } from "./BaseRedisCore.js";
+import type { QueryOptions, RediSearchCreateOptions, RediSearchIndexConfig, RediSearchQueryConfig, RedisResult } from "../../types/RedisTypes.js";
+/**
+ * BaseRedisIndexing
+ *
+ * Extends BaseRedisCore with Redis full-text search and indexing capabilities.
+ * Provides utilities for creating search indexes, syncing collections, and performing
+ * paginated and full-text search queries efficiently.
+ */
+export declare class BaseRedisIndexing extends BaseRedisCore {
+    /** Set of search indexes that have already been ensured */
+    private static readonly ensuredSearchIndexes;
+    /**
+     * Ensures a RediSearch index exists.
+     * Skips creation if the index has already been ensured.
+     * @param params Object containing `indexKey`, `schema`, and optional `options`
+     */
+    protected ensureSearchIndex: (params: {
+        indexKey: string;
+        schema: RediSearchSchema;
+        options?: RediSearchCreateOptions;
+    }) => Promise<void>;
+    /**
+     * Syncs a collection of items into Redis with bounded memory.
+     * Supports indexing, hash storage, TTL, and batch deletion of overflow.
+     * @template T - Type of items to sync
+     * @param params Object containing items, idSelector, scoreSelector, indexKey, itemPrefix, maxItems, TTL, batchSize, and optional search config
+     */
+    protected syncIndexedCollection: <T>(params: {
+        items: T[];
+        idSelector: (item: T) => string | number;
+        scoreSelector: (item: T) => number | Date;
+        indexKey: string;
+        itemPrefix: string;
+        maxItems: number;
+        ttlSeconds?: number;
+        batchSize?: number;
+        search?: RediSearchIndexConfig<T>;
+    }) => Promise<void>;
+    /**
+     * Performs a full-text search query on an indexed collection.
+     * Supports pagination, sorting, and missing key recovery.
+     * @template T - Type of returned items
+     * @param params Object containing search config, optional itemPrefix, query options, and maxLimit
+     * @returns Promise resolving to RedisResult with rows, count, page info, and hasNextPage
+     */
+    protected searchIndexedItems: <T>(params: {
+        search: RediSearchQueryConfig;
+        itemPrefix?: string;
+        options?: QueryOptions;
+        maxLimit?: number;
+    }) => Promise<RedisResult<T>>;
+    /**
+     * Retrieves items directly from a sorted index with strict pagination.
+     * No fallback full scan; index-aligned sorting only.
+     * @template T - Type of returned items
+     * @param params Object containing indexKey, itemPrefix, query options, maxLimit, and optional search config
+     * @returns Promise resolving to RedisResult with rows, count, page info, and hasNextPage
+     */
+    protected getIndexedItems: <T>(params: {
+        indexKey: string;
+        itemPrefix: string;
+        options?: QueryOptions;
+        maxLimit?: number;
+        search?: RediSearchQueryConfig;
+    }) => Promise<RedisResult<T>>;
+    /**
+     * Ensures a full-text search index exists for a given config and item prefix.
+     * @template T - Type of items in the index
+     * @param config RediSearch index configuration
+     * @param itemPrefix Prefix used for all keys in the index
+     */
+    protected syncFTIndex<T>(config: RediSearchIndexConfig<T>, itemPrefix: string): Promise<void>;
+}

package/dist/utils/BaseRedis/RedisQueryHelper.d.ts

@@ -0,0 +1,13 @@
+import type { QueryOptions, RediSearchQueryConfig } from "../../types/RedisTypes.js";
+import type { ParsedQs } from "qs";
+export declare function parseQueryOptions(query: ParsedQs): QueryOptions;
+export declare function parseRediSearchQueryConfig(query: ParsedQs, config: {
+    indexKey: string;
+    defaultSortBy?: string;
+    defaultReturnFields?: string[];
+    defaultDialect?: number;
+    searchParam?: string;
+    sortByParam?: string;
+    returnFieldsParam?: string;
+    dialectParam?: string;
+}): RediSearchQueryConfig;

package/dist/utils/BaseRedis/index.d.ts

@@ -0,0 +1,4 @@
+export type { QueryOptions, RediSearchFieldValue, RediSearchCreateOptions, RediSearchIndexConfig, RediSearchQueryConfig, RedisResult, } from "../../types/RedisTypes.js";
+export { BaseRedisCore } from "./BaseRedisCore.js";
+export { BaseRedisIndexing } from "./BaseRedisIndexing.js";
+export { BaseRedisCrud, BaseRedisCrud as BaseRedis } from "./BaseRedisCrud.js";

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@beespoke/micro-server-redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.3",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "default": "./dist/plugin/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts"
+  },
+  "dependencies": {
+    "redis": "^5.11.0",
+    "@types/qs": "^6.9.15",
+    "@types/node": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@beespoke/micro-server": "^2.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@beespoke/micro-server": {
+      "optional": true
+    }
+  }
+}