@krizaka/realtime 0.0.0-stage → 0.1.0

package/dist/redis.js

@@ -0,0 +1,163 @@
+import {
+  DEFAULT_PRESENCE,
+  emitSafely,
+  localEmitter,
+  rank
+} from "./chunk-HJCRR3FF.js";
+
+// src/redis.ts
+import { Redis } from "ioredis";
+var DEFAULT_PREFIX = "rt:";
+var UPDATE = `
+local key, seen = KEYS[1], KEYS[2]
+local op, conn, st = ARGV[1], ARGV[2], ARGV[3]
+local now, ttl, grace, keep = tonumber(ARGV[4]), tonumber(ARGV[5]), tonumber(ARGV[6]), tonumber(ARGV[7])
+if op == "beat" then
+  redis.call("HSET", key, "c:" .. conn, st .. "|" .. (now + ttl))
+elseif op == "leave" then
+  local cur = redis.call("HGET", key, "c:" .. conn)
+  if cur then
+    local s, exp = string.match(cur, "^(%a+)|(%d+)$")
+    redis.call("HSET", key, "c:" .. conn, s .. "|" .. math.min(tonumber(exp), now + grace))
+  end
+end
+local best = 0
+local all = redis.call("HGETALL", key)
+for i = 1, #all, 2 do
+  local f, v = all[i], all[i + 1]
+  if string.sub(f, 1, 2) == "c:" then
+    local s, exp = string.match(v, "^(%a+)|(%d+)$")
+    if tonumber(exp) <= now then
+      redis.call("HDEL", key, f)
+    else
+      local r = 1
+      if s == "online" then r = 2 end
+      if r > best then best = r end
+    end
+  end
+end
+local nextState = "offline"
+if best == 2 then nextState = "online" elseif best == 1 then nextState = "away" end
+local prev = redis.call("HGET", key, "a") or "offline"
+if nextState == "offline" then
+  if prev ~= "offline" then redis.call("SET", seen, now, "EX", keep) end
+  redis.call("DEL", key)
+else
+  redis.call("HSET", key, "a", nextState)
+  redis.call("PEXPIRE", key, ttl * 2)
+  redis.call("SET", seen, now, "EX", keep)
+end
+if nextState == prev then return false end
+return nextState
+`;
+var RedisPresence = class {
+  constructor(redis, prefix, options = {}) {
+    this.redis = redis;
+    this.prefix = prefix;
+    this.options = { ...DEFAULT_PRESENCE, ...options };
+    this.keep = options.lastSeenTtlSeconds ?? 90 * 24 * 3600;
+  }
+  redis;
+  prefix;
+  options;
+  keep;
+  // The {user} hash tag keeps both keys in one slot (Redis Cluster).
+  keys(userId) {
+    return [`${this.prefix}p:{${userId}}`, `${this.prefix}s:{${userId}}`];
+  }
+  async run(op, userId, connectionId, state, now) {
+    const [key, seen] = this.keys(userId);
+    const result = await this.redis.eval(UPDATE, 2, key, seen, op, connectionId, state, now, this.options.ttlMs, this.options.graceMs, this.keep);
+    return result ? { userId, state: result, at: now } : null;
+  }
+  beat(userId, connectionId, state, now = Date.now()) {
+    return this.run("beat", userId, connectionId, state, now);
+  }
+  leave(userId, connectionId, now = Date.now()) {
+    return this.run("leave", userId, connectionId, "online", now);
+  }
+  settle(userId, now = Date.now()) {
+    return this.run("settle", userId, "", "online", now);
+  }
+  /** Every change is the answer of the call that caused it: nothing is discovered later. */
+  onChange() {
+    return () => void 0;
+  }
+  async get(userIds, now = Date.now()) {
+    const out = /* @__PURE__ */ new Map();
+    if (userIds.length === 0) return out;
+    const pipeline = this.redis.pipeline();
+    for (const id of userIds) {
+      const [key, seen] = this.keys(id);
+      pipeline.hgetall(key);
+      pipeline.get(seen);
+    }
+    const replies = await pipeline.exec() ?? [];
+    userIds.forEach((id, i) => {
+      const hash = replies[i * 2]?.[1] ?? {};
+      const seen = replies[i * 2 + 1]?.[1];
+      let state = "offline";
+      for (const [field, value] of Object.entries(hash)) {
+        if (!field.startsWith("c:")) continue;
+        const [s, exp] = value.split("|");
+        if (Number(exp) > now && rank(s) > rank(state)) state = s;
+      }
+      out.set(id, { state, lastSeenAt: state === "offline" ? seen ? Number(seen) : null : now });
+    });
+    return out;
+  }
+};
+function redisBus(options) {
+  const prefix = options.prefix ?? DEFAULT_PREFIX;
+  const base = { maxRetriesPerRequest: 2, enableOfflineQueue: true, ...options.redisOptions };
+  const pub = new Redis(options.url, base);
+  const sub = new Redis(options.url, { ...base, maxRetriesPerRequest: null });
+  const emitter = localEmitter();
+  const counts = /* @__PURE__ */ new Map();
+  for (const client of [pub, sub]) client.on("error", (error) => console.warn(`[realtime] redis: ${error.message}`));
+  sub.on("message", (channel, message) => {
+    if (!channel.startsWith(prefix)) return;
+    try {
+      emitSafely(emitter, channel.slice(prefix.length), JSON.parse(message));
+    } catch {
+    }
+  });
+  return {
+    kind: "redis",
+    get connected() {
+      return sub.status === "ready" && pub.status === "ready";
+    },
+    presence: new RedisPresence(pub, prefix, options),
+    async publish(channel, event) {
+      try {
+        await pub.publish(prefix + channel, JSON.stringify(event));
+      } catch (error) {
+        console.warn(`[realtime] publish ${channel} failed, delivered locally`, error.message);
+        emitSafely(emitter, channel, event);
+      }
+    },
+    subscribe(channel, handler) {
+      emitter.on(channel, handler);
+      const n = (counts.get(channel) ?? 0) + 1;
+      counts.set(channel, n);
+      if (n === 1) void sub.subscribe(prefix + channel).catch((error) => console.warn(`[realtime] subscribe ${channel}: ${error.message}`));
+      return () => {
+        emitter.off(channel, handler);
+        const left = (counts.get(channel) ?? 1) - 1;
+        if (left > 0) return void counts.set(channel, left);
+        counts.delete(channel);
+        void sub.unsubscribe(prefix + channel).catch(() => void 0);
+      };
+    },
+    async close() {
+      emitter.removeAllListeners();
+      await Promise.allSettled([pub.quit(), sub.quit()]);
+    }
+  };
+}
+export {
+  DEFAULT_PREFIX,
+  RedisPresence,
+  redisBus
+};
+//# sourceMappingURL=redis.js.map

package/dist/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/redis.ts"],"sourcesContent":["import { Redis, type RedisOptions } from \"ioredis\";\n\nimport { emitSafely, localEmitter } from \"./memory\";\nimport { type ConnectionState, DEFAULT_PRESENCE, type PresenceInfo, type PresenceOptions, type PresenceState, type PresenceStore, rank, type RealtimeBus } from \"./types\";\n\nexport interface RedisBusOptions extends Partial<PresenceOptions> {\n  /** `redis://` or `rediss://` (Redis or Valkey — DigitalOcean Managed Caching speaks the same protocol). */\n  url: string;\n  /** Prefix of every key and channel (several products can share one server). Default `DEFAULT_PREFIX`. */\n  prefix?: string;\n  /** How long \"last seen\" is kept (seconds). */\n  lastSeenTtlSeconds?: number;\n  redisOptions?: RedisOptions;\n}\n\n/** The key and channel prefix used when none is given — give each app its own when they share a server. */\nexport const DEFAULT_PREFIX = \"rt:\";\n\n/**\n * One person's presence, atomically: apply the operation, drop expired connections, compare the best remaining state\n * with the announced one. Returns the new state when it changed (announce it), nil otherwise.\n * KEYS: the person's hash (`c:<connection>` = \"<state>|<expiresAt>\", `a` = announced), their last-seen key.\n */\nconst UPDATE = `\nlocal key, seen = KEYS[1], KEYS[2]\nlocal op, conn, st = ARGV[1], ARGV[2], ARGV[3]\nlocal now, ttl, grace, keep = tonumber(ARGV[4]), tonumber(ARGV[5]), tonumber(ARGV[6]), tonumber(ARGV[7])\nif op == \"beat\" then\n  redis.call(\"HSET\", key, \"c:\" .. conn, st .. \"|\" .. (now + ttl))\nelseif op == \"leave\" then\n  local cur = redis.call(\"HGET\", key, \"c:\" .. conn)\n  if cur then\n    local s, exp = string.match(cur, \"^(%a+)|(%d+)$\")\n    redis.call(\"HSET\", key, \"c:\" .. conn, s .. \"|\" .. math.min(tonumber(exp), now + grace))\n  end\nend\nlocal best = 0\nlocal all = redis.call(\"HGETALL\", key)\nfor i = 1, #all, 2 do\n  local f, v = all[i], all[i + 1]\n  if string.sub(f, 1, 2) == \"c:\" then\n    local s, exp = string.match(v, \"^(%a+)|(%d+)$\")\n    if tonumber(exp) <= now then\n      redis.call(\"HDEL\", key, f)\n    else\n      local r = 1\n      if s == \"online\" then r = 2 end\n      if r > best then best = r end\n    end\n  end\nend\nlocal nextState = \"offline\"\nif best == 2 then nextState = \"online\" elseif best == 1 then nextState = \"away\" end\nlocal prev = redis.call(\"HGET\", key, \"a\") or \"offline\"\nif nextState == \"offline\" then\n  if prev ~= \"offline\" then redis.call(\"SET\", seen, now, \"EX\", keep) end\n  redis.call(\"DEL\", key)\nelse\n  redis.call(\"HSET\", key, \"a\", nextState)\n  redis.call(\"PEXPIRE\", key, ttl * 2)\n  redis.call(\"SET\", seen, now, \"EX\", keep)\nend\nif nextState == prev then return false end\nreturn nextState\n`;\n\n/** Presence in Redis / Valkey: shared by every instance, one atomic script per beat, keys that expire by themselves. */\nexport class RedisPresence implements PresenceStore {\n  readonly options: PresenceOptions;\n  private readonly keep: number;\n\n  constructor(\n    private readonly redis: Redis,\n    private readonly prefix: string,\n    options: Partial<PresenceOptions> & { lastSeenTtlSeconds?: number } = {},\n  ) {\n    this.options = { ...DEFAULT_PRESENCE, ...options };\n    this.keep = options.lastSeenTtlSeconds ?? 90 * 24 * 3600;\n  }\n\n  // The {user} hash tag keeps both keys in one slot (Redis Cluster).\n  private keys(userId: string) {\n    return [`${this.prefix}p:{${userId}}`, `${this.prefix}s:{${userId}}`];\n  }\n\n  private async run(op: \"beat\" | \"leave\" | \"settle\", userId: string, connectionId: string, state: ConnectionState, now: number) {\n    const [key, seen] = this.keys(userId);\n    const result = (await this.redis.eval(UPDATE, 2, key, seen, op, connectionId, state, now, this.options.ttlMs, this.options.graceMs, this.keep)) as string | null;\n    return result ? { userId, state: result as PresenceState, at: now } : null;\n  }\n\n  beat(userId: string, connectionId: string, state: ConnectionState, now = Date.now()) {\n    return this.run(\"beat\", userId, connectionId, state, now);\n  }\n\n  leave(userId: string, connectionId: string, now = Date.now()) {\n    return this.run(\"leave\", userId, connectionId, \"online\", now);\n  }\n\n  settle(userId: string, now = Date.now()) {\n    return this.run(\"settle\", userId, \"\", \"online\", now);\n  }\n\n  /** Every change is the answer of the call that caused it: nothing is discovered later. */\n  onChange(): () => void {\n    return () => undefined;\n  }\n\n  async get(userIds: string[], now = Date.now()) {\n    const out = new Map<string, PresenceInfo>();\n    if (userIds.length === 0) return out;\n    const pipeline = this.redis.pipeline();\n    for (const id of userIds) {\n      const [key, seen] = this.keys(id);\n      pipeline.hgetall(key);\n      pipeline.get(seen);\n    }\n    const replies = (await pipeline.exec()) ?? [];\n    userIds.forEach((id, i) => {\n      const hash = (replies[i * 2]?.[1] ?? {}) as Record<string, string>;\n      const seen = replies[i * 2 + 1]?.[1] as string | null;\n      let state: PresenceState = \"offline\";\n      for (const [field, value] of Object.entries(hash)) {\n        if (!field.startsWith(\"c:\")) continue;\n        const [s, exp] = value.split(\"|\");\n        if (Number(exp) > now && rank(s as ConnectionState) > rank(state)) state = s as ConnectionState;\n      }\n      out.set(id, { state, lastSeenAt: state === \"offline\" ? (seen ? Number(seen) : null) : now });\n    });\n    return out;\n  }\n}\n\n/**\n * Redis / Valkey pub/sub: each instance subscribes only to the channels its open streams need (one subscription per\n * channel, counted), so an event crosses the network only to the instances that have someone listening — the choice\n * for several instances and many streams. Presence lives in Redis (`RedisPresence`).\n */\nexport function redisBus(options: RedisBusOptions): RealtimeBus {\n  const prefix = options.prefix ?? DEFAULT_PREFIX;\n  const base: RedisOptions = { maxRetriesPerRequest: 2, enableOfflineQueue: true, ...options.redisOptions };\n  const pub = new Redis(options.url, base);\n  const sub = new Redis(options.url, { ...base, maxRetriesPerRequest: null });\n  const emitter = localEmitter();\n  const counts = new Map<string, number>();\n  for (const client of [pub, sub]) client.on(\"error\", (error) => console.warn(`[realtime] redis: ${error.message}`));\n\n  sub.on(\"message\", (channel: string, message: string) => {\n    if (!channel.startsWith(prefix)) return;\n    try {\n      emitSafely(emitter, channel.slice(prefix.length), JSON.parse(message));\n    } catch {\n      /* not ours */\n    }\n  });\n\n  return {\n    kind: \"redis\",\n    get connected() {\n      return sub.status === \"ready\" && pub.status === \"ready\";\n    },\n    presence: new RedisPresence(pub, prefix, options),\n    async publish(channel, event) {\n      try {\n        await pub.publish(prefix + channel, JSON.stringify(event));\n      } catch (error) {\n        console.warn(`[realtime] publish ${channel} failed, delivered locally`, (error as Error).message);\n        emitSafely(emitter, channel, event);\n      }\n    },\n    subscribe(channel, handler) {\n      emitter.on(channel, handler);\n      const n = (counts.get(channel) ?? 0) + 1;\n      counts.set(channel, n);\n      if (n === 1) void sub.subscribe(prefix + channel).catch((error: Error) => console.warn(`[realtime] subscribe ${channel}: ${error.message}`));\n      return () => {\n        emitter.off(channel, handler);\n        const left = (counts.get(channel) ?? 1) - 1;\n        if (left > 0) return void counts.set(channel, left);\n        counts.delete(channel);\n        void sub.unsubscribe(prefix + channel).catch(() => undefined);\n      };\n    },\n    async close() {\n      emitter.removeAllListeners();\n      await Promise.allSettled([pub.quit(), sub.quit()]);\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/sse.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Server-Sent Events, framed by hand (the format is four fields). `eventStream` turns a few callbacks into a web
+ * `Response` any runtime serves: heartbeats keep proxies from closing an idle stream, `retry` tells the browser how
+ * fast to come back, and a maximum lifetime ends the stream cleanly before a platform's own request timeout does
+ * (the client reconnects at once, with `Last-Event-ID`).
+ */
+interface SseFrame {
+    /** The event's id: the browser sends the last one back as `Last-Event-ID` when it reconnects. */
+    id?: string;
+    /** A named event (`addEventListener(name)`); absent: `message`. */
+    event?: string;
+    data?: unknown;
+    /** Reconnection delay the client should use (ms). */
+    retry?: number;
+    /** A comment line (heartbeats). */
+    comment?: string;
+}
+declare function sseFrame(frame: SseFrame): string;
+interface EventStreamControls {
+    send(frame: SseFrame): void;
+    /** Ends the stream from the server side (the client reconnects). */
+    close(): void;
+    /** Aborted when the client goes away or the stream ends. */
+    signal: AbortSignal;
+}
+interface EventStreamOptions {
+    /** Runs once the stream is open; returns the cleanup to run when it ends. */
+    start(controls: EventStreamControls): void | (() => void) | Promise<void | (() => void)>;
+    /** Heartbeat period (ms) — below every proxy's idle timeout. */
+    heartbeatMs?: number;
+    /** Called at each heartbeat (presence refreshes its TTL there). */
+    onHeartbeat?: () => void;
+    /** Ends the stream after this long (ms, 0: never) — under a platform's hard request timeout. */
+    maxLifetimeMs?: number;
+    /** Reconnection delay sent to the client (ms). */
+    retryMs?: number;
+    headers?: Record<string, string>;
+}
+declare function eventStream(options: EventStreamOptions): Response;
+
+export { type EventStreamControls, type EventStreamOptions, type SseFrame, eventStream, sseFrame };

package/dist/sse.js

@@ -0,0 +1,9 @@
+import {
+  eventStream,
+  sseFrame
+} from "./chunk-GBVW7BAQ.js";
+export {
+  eventStream,
+  sseFrame
+};
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-BP1h40fn.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The realtime contract. Application code knows these interfaces only; which adapter carries them (memory, PostgreSQL
+ * LISTEN/NOTIFY, Redis / Valkey) is a deployment choice (`createBus`).
+ */
+type Unsubscribe = () => void;
+/** What a connection says about its person: in front of the screen, or connected but idle / hidden. */
+type ConnectionState = "online" | "away";
+/** A person's presence: the best state among their connections, `offline` when none is left. */
+type PresenceState = ConnectionState | "offline";
+interface PresenceInfo {
+    state: PresenceState;
+    /** Epoch ms the person was last connected (null: never seen by this store — the caller may know better). */
+    lastSeenAt: number | null;
+}
+/** A person's presence changed (the store announces each change once, whichever instance noticed it). */
+interface PresenceChange {
+    userId: string;
+    state: PresenceState;
+    at: number;
+}
+interface PresenceOptions {
+    /** How long a connection counts without a new beat (ms). Beats come at a third of it. */
+    ttlMs: number;
+    /** How long a closed connection still counts (ms): a reconnection inside it changes nothing (no offline flicker). */
+    graceMs: number;
+}
+/**
+ * Who is connected, kept by heartbeat and time-to-live — never a database write per beat. Every method answers the
+ * change it caused, if any, so the caller publishes it once.
+ */
+interface PresenceStore {
+    /** A connection is (still) there, in this state: opens it or refreshes its TTL. */
+    beat(userId: string, connectionId: string, state: ConnectionState, now?: number): Promise<PresenceChange | null>;
+    /** A connection closed: it lingers `graceMs`, then the person may be offline — `settle` tells. */
+    leave(userId: string, connectionId: string, now?: number): Promise<PresenceChange | null>;
+    /** Re-evaluates a person after expiries (the caller runs it once the grace has passed). */
+    settle(userId: string, now?: number): Promise<PresenceChange | null>;
+    /** The presence of these people (absent from the store: offline, last seen unknown). */
+    get(userIds: string[], now?: number): Promise<Map<string, PresenceInfo>>;
+    /**
+     * Changes this instance discovers on its own rather than as the answer to a call (another instance's report that
+     * makes a person offline). Announce them like the others. Returns the unsubscribe function.
+     */
+    onChange(listener: (change: PresenceChange) => void): Unsubscribe;
+}
+type BusKind = "memory" | "postgres" | "redis";
+/**
+ * The bus: events by channel to every subscriber of every instance, and presence. Best-effort by design — a publish
+ * never throws; durable facts (messages) live in the database and are replayed from it, never from the bus.
+ */
+interface RealtimeBus {
+    readonly kind: BusKind;
+    /** True while events published by other instances reach this one (always true for `memory`). */
+    readonly connected: boolean;
+    readonly presence: PresenceStore;
+    publish(channel: string, event: unknown): Promise<void>;
+    subscribe(channel: string, handler: (event: unknown) => void): Unsubscribe;
+    close(): Promise<void>;
+}
+declare const DEFAULT_PRESENCE: PresenceOptions;
+/** The rank of a state: a person is as present as their most present connection. */
+declare const rank: (state: PresenceState) => 0 | 2 | 1;
+
+export { type BusKind as B, type ConnectionState as C, DEFAULT_PRESENCE as D, type PresenceOptions as P, type RealtimeBus as R, type Unsubscribe as U, type PresenceState as a, type PresenceStore as b, type PresenceChange as c, type PresenceInfo as d, rank as r };

package/package.json

@@ -1,6 +1,154 @@
 {
   "name": "@krizaka/realtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Realtime for Node apps behind one interface: a bus (publish / subscribe by channel) and presence (who is connected, by heartbeat and TTL), with memory, PostgreSQL LISTEN/NOTIFY and Redis / Valkey adapters, plus Server-Sent Events framing.",
+  "keywords": [
+    "krizaka",
+    "realtime",
+    "server-sent-events",
+    "sse",
+    "presence",
+    "pubsub",
+    "postgresql",
+    "listen-notify",
+    "redis",
+    "valkey"
+  ],
+  "homepage": "https://github.com/krizaka/krizaka-ui/tree/main/packages/realtime#readme",
+  "bugs": "https://github.com/krizaka/krizaka-ui/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krizaka/krizaka-ui.git",
+    "directory": "packages/realtime"
+  },
+  "license": "Apache-2.0",
+  "author": "Krizaka (https://www.krizaka.com)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sse": {
+      "types": "./dist/sse.d.ts",
+      "import": "./dist/sse.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js"
+    },
+    "./pg": {
+      "types": "./dist/pg.d.ts",
+      "import": "./dist/pg.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "import": "./dist/redis.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "ioredis": "^5.4.0",
+    "pg": "^8.11.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@size-limit/preset-small-lib": "^14.2.0",
+    "@types/node": "^22.15.0",
+    "@types/pg": "^8.15.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "eslint": "^9.39.0",
+    "ioredis": "^5.11.1",
+    "pg": "^8.16.0",
+    "publint": "^0.3.25",
+    "size-limit": "^14.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.11",
+    "@krizaka/config": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "size-limit": [
+    {
+      "name": ".",
+      "path": "dist/index.js",
+      "limit": "4 kB",
+      "gzip": true,
+      "ignore": [
+        "node:crypto",
+        "node:events",
+        "crypto",
+        "events"
+      ]
+    },
+    {
+      "name": "./sse",
+      "path": "dist/sse.js",
+      "limit": "1 kB",
+      "gzip": true,
+      "ignore": [
+        "node:crypto",
+        "node:events",
+        "crypto",
+        "events"
+      ]
+    },
+    {
+      "name": "./pg",
+      "path": "dist/pg.js",
+      "ignore": [
+        "pg",
+        "node:crypto",
+        "node:events",
+        "crypto",
+        "events"
+      ],
+      "limit": "2 kB",
+      "gzip": true
+    },
+    {
+      "name": "./redis",
+      "path": "dist/redis.js",
+      "ignore": [
+        "ioredis",
+        "node:crypto",
+        "node:events",
+        "crypto",
+        "events"
+      ],
+      "limit": "3 kB",
+      "gzip": true
+    }
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "lint": "eslint . --max-warnings 0 && tsc --noEmit --noUnusedLocals --noUnusedParameters --noFallthroughCasesInSwitch --noImplicitReturns",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:integration": "REALTIME_IT=1 vitest run test/bus.integration.test.ts",
+    "size": "size-limit",
+    "publint": "publint && attw --pack . --profile esm-only"
+  }
 }