@absolutejs/sync-pack-counters 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @absolutejs/sync-pack-counters
+
+Read-set-tracked live counters for
+[`@absolutejs/sync`](https://github.com/absolutejs/sync). Define a compute
+function that reads through `db`; the engine re-runs and pushes the new
+value whenever any table the compute read changes. No manual invalidation,
+no polling, no operator graph — just a function.
+
+```bash
+bun add @absolutejs/sync-pack-counters
+```
+
+## Usage
+
+```ts
+import { createSyncEngine } from '@absolutejs/sync/engine';
+import { createCountersPack } from '@absolutejs/sync-pack-counters';
+
+const engine = createSyncEngine();
+engine.registerReader('tasks',         { all: () => db.tasks.list() });
+engine.registerReader('notifications', { all: () => db.notifications.list() });
+
+engine.registerPack(
+	createCountersPack({
+		counters: {
+			// Bare function form.
+			openTasks: async ({ db }) =>
+				(await db.all<Task>('tasks')).filter((t) => !t.done).length,
+
+			// Per-actor counter using ctx.
+			unreadNotifications: async ({ db, ctx }) =>
+				(await db.all<Notification>('notifications'))
+					.filter((n) => n.actorId === ctx.userId && n.readAt === null)
+					.length,
+
+			// Object form when you need a per-counter authorize override —
+			// e.g. a public site-wide stat anyone can subscribe to.
+			totalUsers: {
+				authorize: () => true,
+				compute: async ({ db }) => (await db.all('users')).length,
+			},
+		},
+	}),
+);
+```
+
+Each counter becomes its own reactive query collection named
+`counter:<key>` returning a single row. Subscribe from the client:
+
+```ts
+useSyncCollection<CounterRow>({ collection: 'counter:openTasks' });
+// Emits { id: 'openTasks', key: 'openTasks', value: 3, computedAt: ... }
+```
+
+## Why `defineReactiveQuery`?
+
+The pack is one big use case for sync's read-set tracking: a counter is
+literally "compute a number from one or more tables, and re-emit it when
+those tables change." The engine instruments every `db.all` / `db.get` /
+`db.where` your compute makes, records the resulting dependency set, and
+parks the query on it. Any subsequent change to a touched table triggers
+a re-run; rows that didn't change don't.
+
+Prefer `db.where(table, predicate)` over `db.all(table).filter(...)`
+when possible — `where` records a **range** dependency that re-runs only
+when a change matches the predicate now or matched it before, instead of
+on every change to the table.
+
+## Permissions
+
+The default `authorize` requires the caller's ctx to expose an actor id
+(via `getActorId`, defaulting to `(ctx) => ctx.userId`). Per-counter
+`authorize` overrides this — return `() => true` for a public counter,
+or implement role-based gating.
+
+## What the pack ships
+
+| Surface              | Name                  | What it does                               |
+| -------------------- | --------------------- | ------------------------------------------ |
+| Reactive query (×N)  | `counter:<key>`       | One per counter; emits a single CounterRow |
+
+The pack owns no tables and reads no tables of its own — every counter's
+read-set comes from the host's registered readers. `engine.inspect().packs[0]`
+reports empty `ownsTables` and `readsTables`.
+
+## Multiple instances
+
+Pass `prefix` to coexist with another counters pack instance:
+
+```ts
+engine.registerPack(createCountersPack({ prefix: 'team_', counters: { ... } }));
+engine.registerPack(createCountersPack({ prefix: 'org_',  counters: { ... } }));
+// Collections: team_counter:<key> and org_counter:<key>
+```

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `@absolutejs/sync-pack-counters` — read-set-tracked live counts.
+ *
+ * Each counter is a `defineReactiveQuery` whose compute function reads
+ * through `ctx.db` to derive a numeric value from host tables. The engine
+ * re-runs the query (and pushes the new value to subscribers) whenever any
+ * table it read changes — no manual invalidation, no operator graph, no
+ * polling. Counters are derived views; the pack owns no tables.
+ *
+ * @example
+ * ```ts
+ * import { createSyncEngine } from '@absolutejs/sync/engine';
+ * import { createCountersPack } from '@absolutejs/sync-pack-counters';
+ *
+ * const engine = createSyncEngine();
+ * engine.registerReader('tasks',         { all: () => db.tasks.list() });
+ * engine.registerReader('notifications', { all: () => db.notifications.list() });
+ *
+ * engine.registerPack(createCountersPack({
+ *   counters: {
+ *     openTasks: async ({ db }) =>
+ *       (await db.all<Task>('tasks')).filter((task) => !task.done).length,
+ *     unreadNotifications: async ({ db, ctx }) =>
+ *       (await db.all<Notification>('notifications'))
+ *         .filter((n) => n.actorId === ctx.userId && n.readAt === null)
+ *         .length,
+ *   },
+ * }));
+ *
+ * // Subscribe to a single counter — emits one row { id, key, value }.
+ * useSyncCollection<CounterRow>({ collection: 'counter:openTasks' });
+ * ```
+ */
+import { type CollectionContext, type ReadHandle, type SyncPack } from '@absolutejs/sync/engine';
+/** One reactive count emission. */
+export type CounterRow = {
+    /** Row key — matches the counter's name. */
+    id: string;
+    key: string;
+    value: number;
+    /** Epoch ms the compute completed. Useful for "as of" labelling. */
+    computedAt: number;
+};
+/** What a counter's `compute` sees. Same shape as a reactive query's run-context. */
+export type CounterContext<Ctx> = {
+    db: ReadHandle;
+    ctx: Ctx;
+};
+/** Function form — convenience when no per-counter authorize override is needed. */
+export type CounterCompute<Ctx> = (context: CounterContext<Ctx>) => number | Promise<number>;
+/** Full form — `compute` + per-counter `authorize` override. */
+export type CounterDefinition<Ctx = CollectionContext> = {
+    /**
+     * Compute the counter value. Reads through `db` are tracked — the
+     * query re-runs whenever any table this compute read changes. Use
+     * `db.where(...)` when possible for range-level dependencies that
+     * are cheaper than full-table.
+     */
+    compute: CounterCompute<Ctx>;
+    /**
+     * Optional access control. Return false (or throw) to deny the
+     * subscription. Default: any ctx with a defined `getActorId` value.
+     * For a "global" counter (e.g. site-wide stats visible to everyone),
+     * return `() => true`.
+     */
+    authorize?: (ctx: Ctx) => boolean | Promise<boolean>;
+};
+/** A counter is either a bare compute function or a full definition object. */
+export type CounterEntry<Ctx = CollectionContext> = CounterCompute<Ctx> | CounterDefinition<Ctx>;
+export type CountersPackConfig<Ctx = CollectionContext> = {
+    prefix?: string;
+    /**
+     * Used by the default `authorize` to gate counter subscriptions to
+     * authenticated callers. Override `authorize` per-counter for global
+     * counters. Default `(ctx) => ctx.userId`.
+     */
+    getActorId?: (ctx: Ctx) => string | undefined;
+    /**
+     * Counter definitions keyed by name. Each value can be a bare compute
+     * function (the common case) or a full {@link CounterDefinition} when
+     * you need to override the default authorize.
+     */
+    counters: Record<string, CounterEntry<Ctx>>;
+};
+/**
+ * Build a {@link SyncPack} that exposes read-set-tracked counters. Each
+ * entry in `config.counters` becomes a separate reactive query named
+ * `${prefix}counter:${key}` returning a single {@link CounterRow}.
+ */
+export declare const createCountersPack: <Ctx = CollectionContext>(config: CountersPackConfig<Ctx>) => SyncPack;

package/dist/index.js

@@ -0,0 +1,46 @@
+// @bun
+// src/index.ts
+import {
+  defineReactiveQuery,
+  defineSyncPack
+} from "@absolutejs/sync/engine";
+var asCounterDefinition = (entry) => typeof entry === "function" ? { compute: entry } : entry;
+var now = () => Date.now();
+var createCountersPack = (config) => {
+  const prefix = config.prefix ?? "";
+  const getActorId = config.getActorId ?? ((ctx) => ctx.userId);
+  const reactiveQueries = Object.entries(config.counters).map(([key, entry]) => {
+    const counter = asCounterDefinition(entry);
+    const collectionName = `${prefix}counter:${key}`;
+    return defineReactiveQuery({
+      name: collectionName,
+      key: (row) => row.id,
+      run: async ({ db, ctx }) => {
+        const value = await counter.compute({
+          ctx,
+          db
+        });
+        return [{ computedAt: now(), id: key, key, value }];
+      },
+      authorize: (_params, ctx) => {
+        if (counter.authorize !== undefined) {
+          return counter.authorize(ctx);
+        }
+        return getActorId(ctx) !== undefined;
+      }
+    });
+  });
+  return defineSyncPack({
+    name: "@absolutejs/sync-pack-counters",
+    ownsTables: [],
+    readsTables: [],
+    version: "0.1.0",
+    reactiveQueries
+  });
+};
+export {
+  createCountersPack
+};
+
+//# debugId=E612E90E978ACBE464756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * `@absolutejs/sync-pack-counters` — read-set-tracked live counts.\n *\n * Each counter is a `defineReactiveQuery` whose compute function reads\n * through `ctx.db` to derive a numeric value from host tables. The engine\n * re-runs the query (and pushes the new value to subscribers) whenever any\n * table it read changes — no manual invalidation, no operator graph, no\n * polling. Counters are derived views; the pack owns no tables.\n *\n * @example\n * ```ts\n * import { createSyncEngine } from '@absolutejs/sync/engine';\n * import { createCountersPack } from '@absolutejs/sync-pack-counters';\n *\n * const engine = createSyncEngine();\n * engine.registerReader('tasks',         { all: () => db.tasks.list() });\n * engine.registerReader('notifications', { all: () => db.notifications.list() });\n *\n * engine.registerPack(createCountersPack({\n *   counters: {\n *     openTasks: async ({ db }) =>\n *       (await db.all<Task>('tasks')).filter((task) => !task.done).length,\n *     unreadNotifications: async ({ db, ctx }) =>\n *       (await db.all<Notification>('notifications'))\n *         .filter((n) => n.actorId === ctx.userId && n.readAt === null)\n *         .length,\n *   },\n * }));\n *\n * // Subscribe to a single counter — emits one row { id, key, value }.\n * useSyncCollection<CounterRow>({ collection: 'counter:openTasks' });\n * ```\n */\n\nimport {\n\tdefineReactiveQuery,\n\tdefineSyncPack,\n\ttype CollectionContext,\n\ttype ReadHandle,\n\ttype SyncPack\n} from '@absolutejs/sync/engine';\n\n/** One reactive count emission. */\nexport type CounterRow = {\n\t/** Row key — matches the counter's name. */\n\tid: string;\n\tkey: string;\n\tvalue: number;\n\t/** Epoch ms the compute completed. Useful for \"as of\" labelling. */\n\tcomputedAt: number;\n};\n\n/** What a counter's `compute` sees. Same shape as a reactive query's run-context. */\nexport type CounterContext<Ctx> = {\n\tdb: ReadHandle;\n\tctx: Ctx;\n};\n\n/** Function form — convenience when no per-counter authorize override is needed. */\nexport type CounterCompute<Ctx> = (\n\tcontext: CounterContext<Ctx>\n) => number | Promise<number>;\n\n/** Full form — `compute` + per-counter `authorize` override. */\nexport type CounterDefinition<Ctx = CollectionContext> = {\n\t/**\n\t * Compute the counter value. Reads through `db` are tracked — the\n\t * query re-runs whenever any table this compute read changes. Use\n\t * `db.where(...)` when possible for range-level dependencies that\n\t * are cheaper than full-table.\n\t */\n\tcompute: CounterCompute<Ctx>;\n\t/**\n\t * Optional access control. Return false (or throw) to deny the\n\t * subscription. Default: any ctx with a defined `getActorId` value.\n\t * For a \"global\" counter (e.g. site-wide stats visible to everyone),\n\t * return `() => true`.\n\t */\n\tauthorize?: (ctx: Ctx) => boolean | Promise<boolean>;\n};\n\n/** A counter is either a bare compute function or a full definition object. */\nexport type CounterEntry<Ctx = CollectionContext> =\n\t| CounterCompute<Ctx>\n\t| CounterDefinition<Ctx>;\n\nconst asCounterDefinition = <Ctx>(\n\tentry: CounterEntry<Ctx>\n): CounterDefinition<Ctx> =>\n\ttypeof entry === 'function' ? { compute: entry } : entry;\n\nexport type CountersPackConfig<Ctx = CollectionContext> = {\n\tprefix?: string;\n\t/**\n\t * Used by the default `authorize` to gate counter subscriptions to\n\t * authenticated callers. Override `authorize` per-counter for global\n\t * counters. Default `(ctx) => ctx.userId`.\n\t */\n\tgetActorId?: (ctx: Ctx) => string | undefined;\n\t/**\n\t * Counter definitions keyed by name. Each value can be a bare compute\n\t * function (the common case) or a full {@link CounterDefinition} when\n\t * you need to override the default authorize.\n\t */\n\tcounters: Record<string, CounterEntry<Ctx>>;\n};\n\nconst now = () => Date.now();\n\n/**\n * Build a {@link SyncPack} that exposes read-set-tracked counters. Each\n * entry in `config.counters` becomes a separate reactive query named\n * `${prefix}counter:${key}` returning a single {@link CounterRow}.\n */\nexport const createCountersPack = <Ctx = CollectionContext>(\n\tconfig: CountersPackConfig<Ctx>\n): SyncPack => {\n\tconst prefix = config.prefix ?? '';\n\tconst getActorId = (config.getActorId ??\n\t\t((ctx: CollectionContext) =>\n\t\t\t(ctx as { userId?: string }).userId)) as (\n\t\tctx: CollectionContext\n\t) => string | undefined;\n\n\tconst reactiveQueries = Object.entries(config.counters).map(\n\t\t([key, entry]) => {\n\t\t\tconst counter = asCounterDefinition<Ctx>(entry);\n\t\t\tconst collectionName = `${prefix}counter:${key}`;\n\t\t\treturn defineReactiveQuery<CounterRow, void, CollectionContext>({\n\t\t\t\tname: collectionName,\n\t\t\t\tkey: (row) => row.id,\n\t\t\t\trun: async ({ db, ctx }) => {\n\t\t\t\t\tconst value = await counter.compute({\n\t\t\t\t\t\tctx: ctx as Ctx,\n\t\t\t\t\t\tdb\n\t\t\t\t\t});\n\t\t\t\t\treturn [{ computedAt: now(), id: key, key, value }];\n\t\t\t\t},\n\t\t\t\tauthorize: (_params, ctx) => {\n\t\t\t\t\tif (counter.authorize !== undefined) {\n\t\t\t\t\t\treturn counter.authorize(ctx as Ctx);\n\t\t\t\t\t}\n\t\t\t\t\treturn getActorId(ctx) !== undefined;\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\t);\n\n\treturn defineSyncPack({\n\t\tname: '@absolutejs/sync-pack-counters',\n\t\townsTables: [],\n\t\treadsTables: [],\n\t\tversion: '0.1.0',\n\t\treactiveQueries\n\t});\n};\n"
+  ],
+  "mappings": ";;AAkCA;AAAA;AAAA;AAAA;AAoDA,IAAM,sBAAsB,CAC3B,UAEA,OAAO,UAAU,aAAa,EAAE,SAAS,MAAM,IAAI;AAkBpD,IAAM,MAAM,MAAM,KAAK,IAAI;AAOpB,IAAM,qBAAqB,CACjC,WACc;AAAA,EACd,MAAM,SAAS,OAAO,UAAU;AAAA,EAChC,MAAM,aAAc,OAAO,eACzB,CAAC,QACA,IAA4B;AAAA,EAI/B,MAAM,kBAAkB,OAAO,QAAQ,OAAO,QAAQ,EAAE,IACvD,EAAE,KAAK,WAAW;AAAA,IACjB,MAAM,UAAU,oBAAyB,KAAK;AAAA,IAC9C,MAAM,iBAAiB,GAAG,iBAAiB;AAAA,IAC3C,OAAO,oBAAyD;AAAA,MAC/D,MAAM;AAAA,MACN,KAAK,CAAC,QAAQ,IAAI;AAAA,MAClB,KAAK,SAAS,IAAI,UAAU;AAAA,QAC3B,MAAM,QAAQ,MAAM,QAAQ,QAAQ;AAAA,UACnC;AAAA,UACA;AAAA,QACD,CAAC;AAAA,QACD,OAAO,CAAC,EAAE,YAAY,IAAI,GAAG,IAAI,KAAK,KAAK,MAAM,CAAC;AAAA;AAAA,MAEnD,WAAW,CAAC,SAAS,QAAQ;AAAA,QAC5B,IAAI,QAAQ,cAAc,WAAW;AAAA,UACpC,OAAO,QAAQ,UAAU,GAAU;AAAA,QACpC;AAAA,QACA,OAAO,WAAW,GAAG,MAAM;AAAA;AAAA,IAE7B,CAAC;AAAA,GAEH;AAAA,EAEA,OAAO,eAAe;AAAA,IACrB,MAAM;AAAA,IACN,YAAY,CAAC;AAAA,IACb,aAAa,CAAC;AAAA,IACd,SAAS;AAAA,IACT;AAAA,EACD,CAAC;AAAA;",
+  "debugId": "E612E90E978ACBE464756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@absolutejs/sync-pack-counters",
+	"version": "0.1.0",
+	"description": "Read-set-tracked live counters for @absolutejs/sync — define a compute function, get a reactive count derived from host tables",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/absolutejs/sync-packs.git",
+		"directory": "counters"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"license": "CC BY-NC 4.0",
+	"author": "Alex Kahn",
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"absolutejs",
+		"sync",
+		"sync-pack",
+		"counters",
+		"stats",
+		"reactive"
+	],
+	"scripts": {
+		"build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=bun --external @absolutejs/sync && tsc --project tsconfig.build.json",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"format": "prettier --write \"./**/*.{ts,json,md}\"",
+		"release": "bun run format && bun run typecheck && bun run test && bun run build && bun publish"
+	},
+	"peerDependencies": {
+		"@absolutejs/sync": ">= 1.9.2"
+	},
+	"devDependencies": {
+		"@absolutejs/sync": "^1.9.2",
+		"@types/bun": "1.3.14",
+		"prettier": "3.5.3",
+		"typescript": "5.8.3"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": ["dist", "README.md"]
+}