layercache 1.0.1 → 1.0.2

package/README.md

@@ -6,6 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dw/layercache)](https://www.npmjs.com/package/layercache)
 [![license](https://img.shields.io/npm/l/layercache)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-blue)](https://www.typescriptlang.org/)
+[![test coverage](https://img.shields.io/badge/tests-49%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
 
 ```
 L1 hit  ~0.01 ms  ← served from memory, zero network
@@ -44,12 +45,24 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Negative caching** — cache known misses for a short TTL to protect the database
 - **Stale strategies** — `staleWhileRevalidate` and `staleIfError` as opt-in read behavior
 - **TTL jitter** — spread expirations to avoid synchronized stampedes
+- **Sliding & adaptive TTL** — extend TTL on every read or ramp it up for hot keys
+- **Refresh-ahead** — trigger background refresh when TTL drops below a threshold
 - **Best-effort writes** — tolerate partial layer write failures when desired
 - **Bulk reads** — `mget` uses layer-level `getMany()` when available
 - **Distributed tag index** — `RedisTagIndex` keeps tag state consistent across multiple servers
 - **Optional distributed single-flight** — plug in a coordinator to dedupe misses across instances
 - **Cross-server L1 invalidation** — Redis pub/sub bus flushes stale memory on other instances when you write or delete
-- **Metrics** — hit/miss/fetch/backfill counters built in
+- **`wrap()` decorator API** — turn any async function into a cached version with auto-generated keys
+- **Cache warming** — pre-populate layers with a prioritised list of entries at startup
+- **Namespaces** — scope a `CacheStack` to a key prefix for multi-tenant or module isolation
+- **Event hooks** — `EventEmitter`-based events for hits, misses, stale serves, errors, and more
+- **Graceful degradation** — skip a failing layer for a configurable retry window
+- **Circuit breaker** — per-key or global; opens after N failures, recovers after cooldown
+- **Compression** — transparent gzip/brotli in `RedisLayer` with a byte threshold
+- **Metrics & stats** — per-layer hit/miss counters, circuit-breaker trips, degraded operations; HTTP stats handler
+- **Persistence** — `exportState` / `importState` for in-process snapshots; `persistToFile` / `restoreFromFile` for disk
+- **Admin CLI** — `layercache stats | keys | invalidate` against any Redis URL
+- **Framework integrations** — Fastify plugin, tRPC middleware, GraphQL resolver wrapper
 - **MessagePack serializer** — drop-in replacement for lower Redis memory usage
 - **NestJS module** — `CacheStackModule.forRoot(...)` with `@InjectCacheStack()`
 - **Custom layers** — implement the 5-method `CacheLayer` interface to plug in Memcached, DynamoDB, or anything else
@@ -178,6 +191,67 @@ const [user1, user2] = await cache.mget([
 const { hits, misses, fetches, staleHits, refreshes, writeFailures } = cache.getMetrics()
 ```
 
+### `cache.resetMetrics(): void`
+
+Resets all counters to zero — useful for per-interval reporting.
+
+```ts
+cache.resetMetrics()
+```
+
+### `cache.getStats(): CacheStatsSnapshot`
+
+Returns metrics, per-layer degradation state, and the number of in-flight background refreshes.
+
+```ts
+const { metrics, layers, backgroundRefreshes } = cache.getStats()
+// layers: [{ name, isLocal, degradedUntil }]
+```
+
+### `cache.wrap(prefix, fetcher, options?)`
+
+Wraps an async function so every call is transparently cached. The key is derived from the function arguments unless you supply a `keyResolver`.
+
+```ts
+const getUser = cache.wrap('user', (id: number) => db.findUser(id))
+
+const user = await getUser(123) // key → "user:123"
+
+// Custom key resolver
+const getUser = cache.wrap(
+  'user',
+  (id: number) => db.findUser(id),
+  { keyResolver: (id) => String(id), ttl: 300 }
+)
+```
+
+### `cache.warm(entries, options?)`
+
+Pre-populate layers at startup from a prioritised list. Higher `priority` values run first.
+
+```ts
+await cache.warm(
+  [
+    { key: 'config',     fetcher: () => db.getConfig(),     priority: 10 },
+    { key: 'user:1',     fetcher: () => db.findUser(1),     priority: 5  },
+    { key: 'user:2',     fetcher: () => db.findUser(2),     priority: 5  },
+  ],
+  { concurrency: 4, continueOnError: true }
+)
+```
+
+### `cache.namespace(prefix): CacheNamespace`
+
+Returns a scoped view with the same full API (`get`, `set`, `delete`, `clear`, `mget`, `wrap`, `warm`, `invalidateByTag`, `invalidateByPattern`, `getMetrics`). `clear()` only touches `prefix:*` keys.
+
+```ts
+const users = cache.namespace('users')
+const posts = cache.namespace('posts')
+
+await users.set('123', userData)          // stored as "users:123"
+await users.clear()                       // only deletes "users:*"
+```
+
 ---
 
 ## Negative + stale caching
@@ -364,6 +438,200 @@ await cache.set('key', value, { ttl: { local: 15, shared: 600 } })
 
 ---
 
+## Sliding & adaptive TTL
+
+**Sliding TTL** resets the TTL on every read so frequently-accessed keys never expire.
+
+```ts
+const value = await cache.get('session:abc', fetchSession, { slidingTtl: true })
+```
+
+**Adaptive TTL** automatically increases the TTL of hot keys up to a ceiling.
+
+```ts
+await cache.get('popular-post', fetchPost, {
+  adaptiveTtl: {
+    hotAfter: 5,      // ramp up after 5 hits
+    step: 60,         // add 60s per hit
+    maxTtl: 3600      // cap at 1h
+  }
+})
+```
+
+**Refresh-ahead** triggers a background refresh when the remaining TTL drops below a threshold, so callers never see a miss.
+
+```ts
+await cache.get('leaderboard', fetchLeaderboard, {
+  ttl: 120,
+  refreshAhead: 30  // start refreshing when ≤30s remain
+})
+```
+
+---
+
+## Graceful degradation & circuit breaker
+
+**Graceful degradation** marks a layer as degraded on failure and skips it for a retry window, keeping the cache available even if Redis is briefly unreachable.
+
+```ts
+new CacheStack([...], {
+  gracefulDegradation: { retryAfterMs: 10_000 }
+})
+```
+
+**Circuit breaker** opens after repeated fetcher failures for a key, returning `null` instead of hammering a broken downstream.
+
+```ts
+new CacheStack([...], {
+  circuitBreaker: {
+    failureThreshold: 5,  // open after 5 consecutive failures
+    cooldownMs: 30_000    // retry after 30s
+  }
+})
+
+// Or per-operation
+await cache.get('fragile-key', fetch, {
+  circuitBreaker: { failureThreshold: 3, cooldownMs: 10_000 }
+})
+```
+
+---
+
+## Compression
+
+`RedisLayer` can transparently compress values before writing. Values smaller than `compressionThreshold` are stored as-is.
+
+```ts
+new RedisLayer({
+  client: redis,
+  ttl: 300,
+  compression: 'gzip',           // or 'brotli'
+  compressionThreshold: 1_024    // bytes — skip compression for small values
+})
+```
+
+---
+
+## Stats & HTTP endpoint
+
+`cache.getStats()` returns a full snapshot suitable for dashboards or health checks.
+
+```ts
+const stats = cache.getStats()
+// {
+//   metrics: { hits, misses, fetches, circuitBreakerTrips, ... },
+//   layers:  [{ name, isLocal, degradedUntil }],
+//   backgroundRefreshes: 2
+// }
+```
+
+Mount a JSON endpoint with the built-in HTTP handler (works with Express, Fastify, Next.js):
+
+```ts
+import { createCacheStatsHandler } from 'layercache'
+import http from 'node:http'
+
+const statsHandler = createCacheStatsHandler(cache)
+http.createServer(statsHandler).listen(9090)
+// GET / → JSON stats
+```
+
+Or use the Fastify plugin:
+
+```ts
+import { createFastifyLayercachePlugin } from 'layercache/integrations/fastify'
+
+await fastify.register(createFastifyLayercachePlugin(cache, {
+  statsPath: '/cache/stats'   // default; set exposeStatsRoute: false to disable
+}))
+// fastify.cache is now available in all handlers
+```
+
+---
+
+## Persistence & snapshots
+
+Transfer cache state between `CacheStack` instances or survive a restart.
+
+```ts
+// In-memory snapshot
+const snapshot = await cache.exportState()
+await anotherCache.importState(snapshot)
+
+// Disk snapshot
+await cache.persistToFile('./cache-snapshot.json')
+await cache.restoreFromFile('./cache-snapshot.json')
+```
+
+---
+
+## Event hooks
+
+`CacheStack` extends `EventEmitter`. Subscribe to events for monitoring or custom side-effects.
+
+| Event | Payload |
+|-------|---------|
+| `hit` | `{ key, layer }` |
+| `miss` | `{ key }` |
+| `set` | `{ key }` |
+| `delete` | `{ key }` |
+| `stale-serve` | `{ key, state, layer }` |
+| `stampede-dedupe` | `{ key }` |
+| `backfill` | `{ key, fromLayer, toLayer }` |
+| `warm` | `{ key }` |
+| `error` | `{ event, context }` |
+
+```ts
+cache.on('hit',   ({ key, layer }) => metrics.inc('cache.hit',  { layer }))
+cache.on('miss',  ({ key })        => metrics.inc('cache.miss'))
+cache.on('error', ({ event, context }) => logger.error(event, context))
+```
+
+---
+
+## Framework integrations
+
+### tRPC
+
+```ts
+import { createTrpcCacheMiddleware } from 'layercache/integrations/trpc'
+
+const cacheMiddleware = createTrpcCacheMiddleware(cache, 'trpc', { ttl: 60 })
+
+export const cachedProcedure = t.procedure.use(cacheMiddleware)
+```
+
+### GraphQL
+
+```ts
+import { cacheGraphqlResolver } from 'layercache/integrations/graphql'
+
+const resolvers = {
+  Query: {
+    user: cacheGraphqlResolver(cache, 'user', (_root, { id }) => db.findUser(id), {
+      keyResolver: (_root, { id }) => id,
+      ttl: 300
+    })
+  }
+}
+```
+
+---
+
+## Admin CLI
+
+Inspect and manage a Redis-backed cache without writing code.
+
+```bash
+# Requires ioredis
+npx layercache stats     --redis redis://localhost:6379
+npx layercache keys      --redis redis://localhost:6379 --pattern "user:*"
+npx layercache invalidate --redis redis://localhost:6379 --tag user:123
+npx layercache invalidate --redis redis://localhost:6379 --pattern "session:*"
+```
+
+---
+
 ## MessagePack serialization
 
 Reduces Redis memory usage and speeds up serialization for large values:
@@ -512,17 +780,28 @@ Example output from a local run:
 
 ## Comparison
 
-| | node-cache | ioredis | cache-manager | **layercache** |
+| | node-cache-manager | keyv | cacheable | **layercache** |
 |---|:---:|:---:|:---:|:---:|
-| Multi-layer | ❌ | ❌ | △ | ✅ |
+| Multi-layer | △ | Plugin | ❌ | ✅ |
 | Auto backfill | ❌ | ❌ | ❌ | ✅ |
 | Stampede prevention | ❌ | ❌ | ❌ | ✅ |
-| Tag invalidation | ❌ | ❌ | ❌ | ✅ |
+| Tag invalidation | ❌ | ❌ | ✅ | ✅ |
 | Distributed tags | ❌ | ❌ | ❌ | ✅ |
 | Cross-server L1 flush | ❌ | ❌ | ❌ | ✅ |
-| TypeScript-first | ❌ | ✅ | △ | ✅ |
-| NestJS module | ❌ | ❌ | ✅ | ✅ |
-| Custom layers | ❌ | — | △ | ✅ |
+| TypeScript-first | △ | ✅ | ✅ | ✅ |
+| Wrap / decorator API | ✅ | ❌ | ❌ | ✅ |
+| Cache warming | ❌ | ❌ | ❌ | ✅ |
+| Namespaces | ❌ | ✅ | ✅ | ✅ |
+| Sliding / adaptive TTL | ❌ | ❌ | ❌ | ✅ |
+| Event hooks | ✅ | ✅ | ✅ | ✅ |
+| Circuit breaker | ❌ | ❌ | ❌ | ✅ |
+| Graceful degradation | ❌ | ❌ | ❌ | ✅ |
+| Compression | ❌ | ❌ | ✅ | ✅ |
+| Persistence / snapshots | ❌ | ❌ | ❌ | ✅ |
+| Admin CLI | ❌ | ❌ | ❌ | ✅ |
+| Pluggable logger | ❌ | ❌ | ✅ | ✅ |
+| NestJS module | ❌ | ❌ | ❌ | ✅ |
+| Custom layers | △ | ❌ | ❌ | ✅ |
 
 ---
 

package/dist/chunk-IILH5XTS.js

@@ -0,0 +1,103 @@
+// src/invalidation/PatternMatcher.ts
+var PatternMatcher = class {
+  static matches(pattern, value) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+    return regex.test(value);
+  }
+};
+
+// src/invalidation/RedisTagIndex.ts
+var RedisTagIndex = class {
+  client;
+  prefix;
+  scanCount;
+  constructor(options) {
+    this.client = options.client;
+    this.prefix = options.prefix ?? "layercache:tag-index";
+    this.scanCount = options.scanCount ?? 100;
+  }
+  async touch(key) {
+    await this.client.sadd(this.knownKeysKey(), key);
+  }
+  async track(key, tags) {
+    const keyTagsKey = this.keyTagsKey(key);
+    const existingTags = await this.client.smembers(keyTagsKey);
+    const pipeline = this.client.pipeline();
+    pipeline.sadd(this.knownKeysKey(), key);
+    for (const tag of existingTags) {
+      pipeline.srem(this.tagKeysKey(tag), key);
+    }
+    pipeline.del(keyTagsKey);
+    if (tags.length > 0) {
+      pipeline.sadd(keyTagsKey, ...tags);
+      for (const tag of new Set(tags)) {
+        pipeline.sadd(this.tagKeysKey(tag), key);
+      }
+    }
+    await pipeline.exec();
+  }
+  async remove(key) {
+    const keyTagsKey = this.keyTagsKey(key);
+    const existingTags = await this.client.smembers(keyTagsKey);
+    const pipeline = this.client.pipeline();
+    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.del(keyTagsKey);
+    for (const tag of existingTags) {
+      pipeline.srem(this.tagKeysKey(tag), key);
+    }
+    await pipeline.exec();
+  }
+  async keysForTag(tag) {
+    return this.client.smembers(this.tagKeysKey(tag));
+  }
+  async matchPattern(pattern) {
+    const matches = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.sscan(
+        this.knownKeysKey(),
+        cursor,
+        "MATCH",
+        pattern,
+        "COUNT",
+        this.scanCount
+      );
+      cursor = nextCursor;
+      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+    } while (cursor !== "0");
+    return matches;
+  }
+  async clear() {
+    const indexKeys = await this.scanIndexKeys();
+    if (indexKeys.length === 0) {
+      return;
+    }
+    await this.client.del(...indexKeys);
+  }
+  async scanIndexKeys() {
+    const matches = [];
+    let cursor = "0";
+    const pattern = `${this.prefix}:*`;
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      matches.push(...keys);
+    } while (cursor !== "0");
+    return matches;
+  }
+  knownKeysKey() {
+    return `${this.prefix}:keys`;
+  }
+  keyTagsKey(key) {
+    return `${this.prefix}:key:${encodeURIComponent(key)}`;
+  }
+  tagKeysKey(tag) {
+    return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
+  }
+};
+
+export {
+  PatternMatcher,
+  RedisTagIndex
+};

package/dist/cli.cjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  main: () => main
+});
+module.exports = __toCommonJS(cli_exports);
+var import_ioredis = __toESM(require("ioredis"), 1);
+
+// src/invalidation/PatternMatcher.ts
+var PatternMatcher = class {
+  static matches(pattern, value) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+    return regex.test(value);
+  }
+};
+
+// src/invalidation/RedisTagIndex.ts
+var RedisTagIndex = class {
+  client;
+  prefix;
+  scanCount;
+  constructor(options) {
+    this.client = options.client;
+    this.prefix = options.prefix ?? "layercache:tag-index";
+    this.scanCount = options.scanCount ?? 100;
+  }
+  async touch(key) {
+    await this.client.sadd(this.knownKeysKey(), key);
+  }
+  async track(key, tags) {
+    const keyTagsKey = this.keyTagsKey(key);
+    const existingTags = await this.client.smembers(keyTagsKey);
+    const pipeline = this.client.pipeline();
+    pipeline.sadd(this.knownKeysKey(), key);
+    for (const tag of existingTags) {
+      pipeline.srem(this.tagKeysKey(tag), key);
+    }
+    pipeline.del(keyTagsKey);
+    if (tags.length > 0) {
+      pipeline.sadd(keyTagsKey, ...tags);
+      for (const tag of new Set(tags)) {
+        pipeline.sadd(this.tagKeysKey(tag), key);
+      }
+    }
+    await pipeline.exec();
+  }
+  async remove(key) {
+    const keyTagsKey = this.keyTagsKey(key);
+    const existingTags = await this.client.smembers(keyTagsKey);
+    const pipeline = this.client.pipeline();
+    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.del(keyTagsKey);
+    for (const tag of existingTags) {
+      pipeline.srem(this.tagKeysKey(tag), key);
+    }
+    await pipeline.exec();
+  }
+  async keysForTag(tag) {
+    return this.client.smembers(this.tagKeysKey(tag));
+  }
+  async matchPattern(pattern) {
+    const matches = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.sscan(
+        this.knownKeysKey(),
+        cursor,
+        "MATCH",
+        pattern,
+        "COUNT",
+        this.scanCount
+      );
+      cursor = nextCursor;
+      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+    } while (cursor !== "0");
+    return matches;
+  }
+  async clear() {
+    const indexKeys = await this.scanIndexKeys();
+    if (indexKeys.length === 0) {
+      return;
+    }
+    await this.client.del(...indexKeys);
+  }
+  async scanIndexKeys() {
+    const matches = [];
+    let cursor = "0";
+    const pattern = `${this.prefix}:*`;
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      matches.push(...keys);
+    } while (cursor !== "0");
+    return matches;
+  }
+  knownKeysKey() {
+    return `${this.prefix}:keys`;
+  }
+  keyTagsKey(key) {
+    return `${this.prefix}:key:${encodeURIComponent(key)}`;
+  }
+  tagKeysKey(tag) {
+    return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
+  }
+};
+
+// src/cli.ts
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (!args.command || !args.redisUrl) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+  const redis = new import_ioredis.default(args.redisUrl);
+  try {
+    if (args.command === "stats") {
+      const keys = await scanKeys(redis, args.pattern ?? "*");
+      process.stdout.write(`${JSON.stringify({ totalKeys: keys.length, pattern: args.pattern ?? "*" }, null, 2)}
+`);
+      return;
+    }
+    if (args.command === "keys") {
+      const keys = await scanKeys(redis, args.pattern ?? "*");
+      process.stdout.write(`${keys.join("\n")}
+`);
+      return;
+    }
+    if (args.command === "invalidate") {
+      if (args.tag) {
+        const tagIndex = new RedisTagIndex({ client: redis, prefix: args.tagIndexPrefix ?? "layercache:tag-index" });
+        const keys2 = await tagIndex.keysForTag(args.tag);
+        if (keys2.length > 0) {
+          await redis.del(...keys2);
+        }
+        process.stdout.write(`${JSON.stringify({ deletedKeys: keys2.length, tag: args.tag }, null, 2)}
+`);
+        return;
+      }
+      const keys = await scanKeys(redis, args.pattern ?? "*");
+      if (keys.length > 0) {
+        await redis.del(...keys);
+      }
+      process.stdout.write(`${JSON.stringify({ deletedKeys: keys.length, pattern: args.pattern ?? "*" }, null, 2)}
+`);
+      return;
+    }
+    printUsage();
+    process.exitCode = 1;
+  } finally {
+    redis.disconnect();
+  }
+}
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const parsed = { command };
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
+    const value = rest[index + 1];
+    if (token === "--redis") {
+      parsed.redisUrl = value;
+      index += 1;
+    } else if (token === "--pattern") {
+      parsed.pattern = value;
+      index += 1;
+    } else if (token === "--tag") {
+      parsed.tag = value;
+      index += 1;
+    } else if (token === "--tag-index-prefix") {
+      parsed.tagIndexPrefix = value;
+      index += 1;
+    }
+  }
+  return parsed;
+}
+async function scanKeys(redis, pattern) {
+  const keys = [];
+  let cursor = "0";
+  do {
+    const [nextCursor, batch] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
+    cursor = nextCursor;
+    keys.push(...batch);
+  } while (cursor !== "0");
+  return keys;
+}
+function printUsage() {
+  process.stdout.write(
+    "Usage:\n  layercache stats --redis <url> [--pattern <glob>]\n  layercache keys --redis <url> [--pattern <glob>]\n  layercache invalidate --redis <url> [--pattern <glob> | --tag <tag>] [--tag-index-prefix <prefix>]\n"
+  );
+}
+if (process.argv[1]?.includes("cli.")) {
+  void main();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main
+});

package/dist/cli.d.cts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+declare function main(argv?: string[]): Promise<void>;
+
+export { main };

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+declare function main(argv?: string[]): Promise<void>;
+
+export { main };