@profullstack/leaderboard 0.2.0 → 0.3.0

package/README.md

@@ -142,12 +142,33 @@ Every number is an option (`base`, `cap`, `perProperty`, `perNiche`, `maxPropert
 ## Stores
 
 ```js
-import { memoryStore, sqlStore } from '@profullstack/leaderboard';
+import { memoryStore, sqlStore, projectionStore } from '@profullstack/leaderboard';
 
-memoryStore();                                        // one process, tests
+memoryStore();                                           // one process, tests
 sqlStore({ execute, prefix: 'lb_', dialect: 'sqlite' })  // or 'postgres'
+projectionStore({ events, gauges, badges })              // rank tables you already have
 ```
 
+### Ranking data you already record
+
+Most sites that want a leaderboard are already recording the facts it would rank. Copying those into a second set of tables is a dual write, and a dual write means the board and the ledger disagree the first time one of them fails. `projectionStore` reads the source instead:
+
+```js
+const store = projectionStore({
+  events: async ({ since }) => {
+    const rows = await sql`select payer, total_cents, created_at from crawl_sales
+                           where created_at >= ${new Date(since)}`;
+    return rows.map((r) => ({
+      player: r.payer, name: r.payer, metric: 'spent',
+      delta: r.total_cents, at: +new Date(r.created_at),
+    }));
+  },
+  badges: sqlStore({ execute }),   // badges are awarded, not derived, so they need a home
+});
+```
+
+`since` is `0` for an all-time board, so the query has to handle "everything". The store is read-only: `record()` and `set()` throw rather than drop a write the next projection would overwrite.
+
 `sqlStore` needs `execute({ sql, args }) -> { rows }`, which is `@libsql/client` as is. `store.schema` is the DDL for your own migration tool; `store.migrate()` runs it. Three tables: events, gauges, badges.
 
 Anything else implements six methods: `append`, `list({ since })`, `setGauge`, `gauges`, `awardBadge`, `badges`. The core reads all events and aggregates in memory, cached for `cacheMs` (15 s); that is fine into the hundreds of thousands of events. Call `lb.invalidate()` after writing to the store from elsewhere.

package/index.d.ts

@@ -26,6 +26,16 @@ export interface SqlStoreOptions {
 export interface SqlStore extends Store { schema: string[]; tables: { events: string; gauges: string; badges: string }; migrate(): Promise<void> }
 export function sqlStore(options: SqlStoreOptions): SqlStore;
 
+export interface ProjectionOptions {
+  /** Build events from rows you already have. `since` is 0 for all time. */
+  events(opts: { since: number }): Promise<Event[]> | Event[];
+  gauges?(): Promise<Record<string, { name?: string; at: number; values: Record<string, number> }>> | Record<string, { name?: string; at: number; values: Record<string, number> }>;
+  /** Where awarded badges persist. Defaults to memory, which does not survive a restart. */
+  badges?: Pick<Store, 'awardBadge' | 'badges'>;
+}
+/** A read-only store over existing tables. `record()` and `set()` throw. */
+export function projectionStore(options: ProjectionOptions): Store;
+
 export interface LadderOptions {
   base?: number; cap?: number; perProperty?: number; perNiche?: number; maxProperties?: number; maxNiches?: number;
   propertiesMetric?: string; nichesMetric?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/leaderboard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A public leaderboard with badges, streaks and a commission ladder that drops into any site. Ranks either side of a transaction, earners and spenders and usage, kept segregated. Zero dependencies, Fetch API core, Hono and Next adapters.",
   "keywords": [
@@ -60,6 +60,10 @@
     "./store/sql": {
       "types": "./index.d.ts",
       "import": "./src/store/sql.js"
+    },
+    "./store/projection": {
+      "types": "./index.d.ts",
+      "import": "./src/store/projection.js"
     }
   },
   "types": "./index.d.ts",

package/src/index.js

@@ -7,6 +7,7 @@ export { commissionLadder } from './ladder.js';
 export { defaultBadges } from './badges.js';
 export { memoryStore } from './store/memory.js';
 export { sqlStore } from './store/sql.js';
+export { projectionStore } from './store/projection.js';
 
 const DAY = 86_400_000;
 const PERIODS = { all: 0, day: DAY, week: 7 * DAY, month: 30 * DAY };

package/src/store/projection.js

@@ -0,0 +1,58 @@
+import { memoryStore } from './memory.js';
+
+/**
+ * A read-through store over tables you already have.
+ *
+ * Most sites that could show a leaderboard are already recording the facts it
+ * would rank: sales, payments, referral commissions, requests served. Copying
+ * those into a second set of tables means a dual write, and a dual write means
+ * the board and the ledger disagree the first time one of them fails. So
+ * project instead: hand back events built from the rows you already trust.
+ *
+ *   projectionStore({
+ *     events: async ({ since }) => {
+ *       const rows = await sql`select payer, total_cents, created_at from crawl_sales
+ *                              where created_at >= ${new Date(since)}`;
+ *       return rows.map((r) => ({
+ *         player: r.payer, name: r.payer, metric: 'spent',
+ *         delta: r.total_cents, at: +new Date(r.created_at),
+ *       }));
+ *     },
+ *   })
+ *
+ * `since` is 0 for an all-time board, so the query must handle "everything".
+ * Badges still need somewhere durable to live, since they are awarded rather
+ * than derived: pass `badges` (a `sqlStore`, or any object with `awardBadge`
+ * and `badges`). The default keeps them in memory, which is fine for a board
+ * with no badges and wrong for one with them.
+ *
+ * The store is read-only. `record()` and `set()` on a leaderboard backed by a
+ * projection throw, rather than silently dropping a write that the projection
+ * would overwrite on the next read anyway.
+ */
+export function projectionStore({ events, gauges, badges } = {}) {
+  if (typeof events !== 'function') throw new TypeError('projectionStore needs an events({ since }) function');
+  const badgeStore = badges ?? memoryStore();
+  const readOnly = (method) => () => {
+    throw new Error(`${method}() is not available on a projection store: write to the source table instead, the board reads it back`);
+  };
+  return {
+    async list({ since = 0 } = {}) {
+      const rows = (await events({ since })) ?? [];
+      return rows.map((e) => ({
+        player: String(e.player),
+        name: e.name == null ? undefined : String(e.name),
+        metric: String(e.metric),
+        delta: Number(e.delta) || 0,
+        at: Number(e.at) || 0,
+      }));
+    },
+    async gauges() {
+      return (typeof gauges === 'function' ? await gauges() : null) ?? {};
+    },
+    append: readOnly('record'),
+    setGauge: readOnly('set'),
+    awardBadge: (...a) => badgeStore.awardBadge(...a),
+    badges: () => badgeStore.badges(),
+  };
+}