@absolutejs/sync-pack-utils 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# @absolutejs/sync-pack-utils
+
+Shared helpers for [`@absolutejs/sync`](https://github.com/absolutejs/sync)
+packs. Each helper closes one repeated pattern that showed up across the six
+official packs (presence, comments, digest, notifications, favorites,
+counters). The goal: make new packs — first- or third-party — cheaper to
+write and consistent with what's already shipped.
+
+```bash
+bun add @absolutejs/sync-pack-utils
+```
+
+## API
+
+### Actor resolution
+
+```ts
+import {
+	defaultGetActorId,
+	resolveActor,
+} from '@absolutejs/sync-pack-utils';
+
+// (ctx) => ctx.userId — the conventional default.
+const getActorId = config.getActorId ?? defaultGetActorId<MyCtx>();
+
+// Inside a mutation handler: throws UnauthorizedError if no actor id.
+// The context string ends up in the error message so logs name the op.
+const actorId = resolveActor(getActorId, ctx, 'mypack:create');
+```
+
+### Permission builders
+
+```ts
+import {
+	requireRowOwner,
+	requireOwnerOrModerator,
+} from '@absolutejs/sync-pack-utils';
+
+permissions: {
+	[table]: {
+		read: ...,
+		// Owner-only writes — uses row.actorId by default; override the
+		// field name for packs that use authorId, userId, etc.
+		insert: requireRowOwner(getActorId, 'actorId'),
+		update: requireRowOwner(getActorId, 'actorId'),
+		// Owner OR moderator delete. Falls back to store.getById when
+		// actions.delete supplied only the row key (the common case).
+		delete: requireOwnerOrModerator({
+			actorIdField: 'actorId',
+			canModerate,        // optional
+			getActorId,
+			store,              // { getById }
+		}),
+	},
+},
+```
+
+`requireRowOwner` and `requireOwnerOrModerator` are higher-order — call
+them once at pack-build time to receive the per-row predicate the engine
+expects. Both reject when `getActorId(ctx)` is `undefined` (anonymous
+callers can't own a row).
+
+### In-memory store
+
+```ts
+import {
+	createInMemoryStore,
+	type InMemoryStore,
+} from '@absolutejs/sync-pack-utils';
+
+type FavoriteRow = { id: string; actorId: string; /* ... */ };
+
+const store: InMemoryStore<FavoriteRow> =
+	config.store ?? createInMemoryStore<FavoriteRow>();
+
+engine.registerPack(defineSyncPack({
+	// ...
+	readers: { favorites: store.reader },
+	writers: { favorites: store.writer },
+	// store.getById is available for permission + mutation handler use.
+}));
+```
+
+`createInMemoryStore<Row>()` returns:
+
+- `reader: TableReader<CollectionContext>` — `all()` returns `[...rows.values()]`
+- `writer: TableWriter<Row>` — upsert-by-id; `delete` removes by `row.id`
+- `getById(id)` — point lookup
+- `rows: Map<string, Row>` — direct access (treat as read-only)
+
+Every official pack uses this as its default backing store and exposes a
+`store?: ...` config field so consumers can swap in a Postgres / Drizzle /
+Redis implementation when they need persistence.
+
+## What's intentionally not here
+
+- **`prefixed(prefix, ...)`**: just use template literals.
+  ``${prefix}<my-collection>`` is fine.
+- **`defineActorPack(...)`**: a Convex-style abstraction that wraps
+  `defineSyncPack` with permission defaults. Decided against — it'd hide
+  the engine surface, which is the thing pack authors learn first.
+- **Validators / Zod adapters**: out of scope; sync's `field` helper +
+  schema is the validation layer.
+
+## Pairing with `@absolutejs/sync/testing`
+
+Pack tests typically pair with `@absolutejs/sync/testing` (added in sync
+1.9.2):
+
+```ts
+import { expectRejection } from '@absolutejs/sync/testing';
+import { resolveActor } from '@absolutejs/sync-pack-utils';
+
+const error = await expectRejection(() => {
+	resolveActor(getActorId, {}, 'mypack:do');
+	return Promise.resolve();
+});
+expect(error).toBeInstanceOf(UnauthorizedError);
+```
+
+## Versioning
+
+This package stays 0.x indefinitely while the ecosystem settles. When the
+six official packs are stable, the helpers will follow.

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `@absolutejs/sync-pack-utils` — shared helpers extracted from the six
+ * official `@absolutejs/sync` packs.
+ *
+ * Each helper closes one repeated pattern. The goal is to make new packs
+ * (first- and third-party) cheaper to write and stop drift from the
+ * standard shapes already shipped by presence / comments / digest /
+ * notifications / favorites / counters.
+ */
+import { type CollectionContext, type TableReader, type TableWriter } from '@absolutejs/sync/engine';
+/**
+ * The conventional default — `(ctx) => ctx.userId`. Use as the fallback when
+ * a pack's config doesn't supply its own `getActorId`.
+ *
+ * @example
+ * const getActorId = config.getActorId ?? defaultGetActorId<MyCtx>();
+ */
+export declare const defaultGetActorId: <Ctx = CollectionContext>() => ((ctx: Ctx) => string | undefined);
+/**
+ * Resolve the caller's actor id from a ctx, or throw {@link UnauthorizedError}
+ * with a descriptive message. Use inside mutation handlers that require an
+ * actor; the message embeds your `context` string so error reports name the
+ * pack and operation.
+ *
+ * @example
+ * const actorId = resolveActor(getActorId, ctx, 'comments:create');
+ */
+export declare const resolveActor: <Ctx = CollectionContext>(getActorId: (ctx: Ctx) => string | undefined, ctx: unknown, context: string) => string;
+/**
+ * Permission validator that requires `row[actorIdField] === getActorId(ctx)`.
+ * Use for `insert` and `update` on rows the actor owns; the handler stamps
+ * the actor on the row, so this is the canonical row-ownership check.
+ *
+ * @example
+ * permissions: {
+ *   notifications: {
+ *     insert: requireRowOwner(getActorId, 'actorId'),
+ *     update: requireRowOwner(getActorId, 'actorId'),
+ *   },
+ * },
+ */
+export declare const requireRowOwner: <Ctx = CollectionContext>(getActorId: (ctx: Ctx) => string | undefined, actorIdField?: string) => (ctx: unknown, row: unknown) => boolean;
+/**
+ * Permission validator for delete (or any op) that accepts the row OR
+ * just its id. Falls back to `store.getById(row.id)` when the row's actor
+ * field isn't on the supplied subject — sync's engine passes only the
+ * key to `actions.delete({ id })`, so this pattern is needed for every
+ * owner-gated delete.
+ *
+ * Returns true when the row's owner matches the caller OR `canModerate(ctx)`
+ * is `true`.
+ *
+ * @example
+ * permissions: {
+ *   notifications: {
+ *     delete: requireOwnerOrModerator({
+ *       getActorId,
+ *       canModerate,
+ *       store,  // { getById }
+ *       actorIdField: 'actorId',
+ *     }),
+ *   },
+ * },
+ */
+export declare const requireOwnerOrModerator: <Ctx = CollectionContext>(options: {
+    getActorId: (ctx: Ctx) => string | undefined;
+    canModerate?: (ctx: Ctx) => boolean;
+    store: {
+        getById: (id: string) => unknown;
+    };
+    actorIdField?: string;
+}) => (ctx: unknown, row: unknown) => boolean;
+/**
+ * Standard in-memory store for a pack table. Every row needs an `id: string`
+ * (the table's primary key); the writer is upsert-by-id. Used by every
+ * official pack as the default backing store.
+ */
+export type InMemoryStore<Row extends {
+    id: string;
+}> = {
+    reader: TableReader<CollectionContext>;
+    writer: TableWriter<Row, CollectionContext, unknown>;
+    /** Lookup by id — convenient for permission and mutation handlers. */
+    getById: (id: string) => Row | undefined;
+    /** Direct read of the underlying Map for advanced use; treat as read-only. */
+    rows: Map<string, Row>;
+};
+/**
+ * Build a fresh, isolated in-memory store. Each call gets its own Map, so
+ * two pack instances on the same engine don't share state.
+ *
+ * @example
+ * const store = config.store ?? createInMemoryStore<NotificationRow>();
+ */
+export declare const createInMemoryStore: <Row extends {
+    id: string;
+}>() => InMemoryStore<Row>;

package/dist/index.js

@@ -0,0 +1,79 @@
+// @bun
+// src/index.ts
+import {
+  UnauthorizedError
+} from "@absolutejs/sync/engine";
+var defaultGetActorId = () => (ctx) => ctx.userId;
+var resolveActor = (getActorId, ctx, context) => {
+  const actorId = getActorId(ctx);
+  if (actorId === undefined || actorId === "") {
+    throw new UnauthorizedError(`${context} (no actor id)`);
+  }
+  return actorId;
+};
+var requireRowOwner = (getActorId, actorIdField = "actorId") => (ctx, row) => {
+  const callerId = getActorId(ctx);
+  if (callerId === undefined)
+    return false;
+  const rowActor = row[actorIdField];
+  return rowActor === callerId;
+};
+var requireOwnerOrModerator = (options) => (ctx, row) => {
+  const {
+    getActorId,
+    canModerate,
+    store,
+    actorIdField = "actorId"
+  } = options;
+  const callerId = getActorId(ctx);
+  if (callerId === undefined)
+    return false;
+  const supplied = row;
+  const ownerId = supplied[actorIdField] !== undefined ? supplied[actorIdField] : (() => {
+    const id = supplied.id;
+    if (typeof id !== "string")
+      return;
+    const stored = store.getById(id);
+    return stored?.[actorIdField];
+  })();
+  if (ownerId === undefined)
+    return false;
+  if (ownerId === callerId)
+    return true;
+  return canModerate !== undefined ? canModerate(ctx) : false;
+};
+var createInMemoryStore = () => {
+  const rows = new Map;
+  return {
+    getById: (id) => rows.get(id),
+    reader: {
+      all: () => [...rows.values()]
+    },
+    rows,
+    writer: {
+      delete: (row) => {
+        rows.delete(row.id);
+      },
+      insert: (data) => {
+        rows.set(data.id, data);
+        return data;
+      },
+      update: (data) => {
+        const prior = rows.get(data.id);
+        const merged = { ...prior ?? {}, ...data };
+        rows.set(data.id, merged);
+        return merged;
+      }
+    }
+  };
+};
+export {
+  resolveActor,
+  requireRowOwner,
+  requireOwnerOrModerator,
+  defaultGetActorId,
+  createInMemoryStore
+};
+
+//# debugId=EA54D19BA095911A64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * `@absolutejs/sync-pack-utils` — shared helpers extracted from the six\n * official `@absolutejs/sync` packs.\n *\n * Each helper closes one repeated pattern. The goal is to make new packs\n * (first- and third-party) cheaper to write and stop drift from the\n * standard shapes already shipped by presence / comments / digest /\n * notifications / favorites / counters.\n */\n\nimport {\n\tUnauthorizedError,\n\ttype CollectionContext,\n\ttype TableReader,\n\ttype TableWriter\n} from '@absolutejs/sync/engine';\n\n// ─── Actor resolution ────────────────────────────────────────────────────────\n\n/**\n * The conventional default — `(ctx) => ctx.userId`. Use as the fallback when\n * a pack's config doesn't supply its own `getActorId`.\n *\n * @example\n * const getActorId = config.getActorId ?? defaultGetActorId<MyCtx>();\n */\nexport const defaultGetActorId = <\n\tCtx = CollectionContext\n>(): ((ctx: Ctx) => string | undefined) =>\n\t(ctx) => (ctx as { userId?: string }).userId;\n\n/**\n * Resolve the caller's actor id from a ctx, or throw {@link UnauthorizedError}\n * with a descriptive message. Use inside mutation handlers that require an\n * actor; the message embeds your `context` string so error reports name the\n * pack and operation.\n *\n * @example\n * const actorId = resolveActor(getActorId, ctx, 'comments:create');\n */\nexport const resolveActor = <Ctx = CollectionContext>(\n\tgetActorId: (ctx: Ctx) => string | undefined,\n\tctx: unknown,\n\tcontext: string\n): string => {\n\tconst actorId = getActorId(ctx as Ctx);\n\tif (actorId === undefined || actorId === '') {\n\t\tthrow new UnauthorizedError(`${context} (no actor id)`);\n\t}\n\treturn actorId;\n};\n\n// ─── Permission builders ─────────────────────────────────────────────────────\n\n/**\n * Permission validator that requires `row[actorIdField] === getActorId(ctx)`.\n * Use for `insert` and `update` on rows the actor owns; the handler stamps\n * the actor on the row, so this is the canonical row-ownership check.\n *\n * @example\n * permissions: {\n *   notifications: {\n *     insert: requireRowOwner(getActorId, 'actorId'),\n *     update: requireRowOwner(getActorId, 'actorId'),\n *   },\n * },\n */\nexport const requireRowOwner =\n\t<Ctx = CollectionContext>(\n\t\tgetActorId: (ctx: Ctx) => string | undefined,\n\t\tactorIdField: string = 'actorId'\n\t) =>\n\t(ctx: unknown, row: unknown): boolean => {\n\t\tconst callerId = getActorId(ctx as Ctx);\n\t\tif (callerId === undefined) return false;\n\t\tconst rowActor = (row as Record<string, unknown>)[actorIdField];\n\t\treturn rowActor === callerId;\n\t};\n\n/**\n * Permission validator for delete (or any op) that accepts the row OR\n * just its id. Falls back to `store.getById(row.id)` when the row's actor\n * field isn't on the supplied subject — sync's engine passes only the\n * key to `actions.delete({ id })`, so this pattern is needed for every\n * owner-gated delete.\n *\n * Returns true when the row's owner matches the caller OR `canModerate(ctx)`\n * is `true`.\n *\n * @example\n * permissions: {\n *   notifications: {\n *     delete: requireOwnerOrModerator({\n *       getActorId,\n *       canModerate,\n *       store,  // { getById }\n *       actorIdField: 'actorId',\n *     }),\n *   },\n * },\n */\nexport const requireOwnerOrModerator =\n\t<Ctx = CollectionContext>(options: {\n\t\tgetActorId: (ctx: Ctx) => string | undefined;\n\t\tcanModerate?: (ctx: Ctx) => boolean;\n\t\tstore: { getById: (id: string) => unknown };\n\t\tactorIdField?: string;\n\t}) =>\n\t(ctx: unknown, row: unknown): boolean => {\n\t\tconst {\n\t\t\tgetActorId,\n\t\t\tcanModerate,\n\t\t\tstore,\n\t\t\tactorIdField = 'actorId'\n\t\t} = options;\n\t\tconst callerId = getActorId(ctx as Ctx);\n\t\tif (callerId === undefined) return false;\n\t\tconst supplied = row as Record<string, unknown>;\n\t\tconst ownerId =\n\t\t\tsupplied[actorIdField] !== undefined\n\t\t\t\t? supplied[actorIdField]\n\t\t\t\t: (() => {\n\t\t\t\t\t\tconst id = supplied.id;\n\t\t\t\t\t\tif (typeof id !== 'string') return undefined;\n\t\t\t\t\t\tconst stored = store.getById(id) as\n\t\t\t\t\t\t\t| Record<string, unknown>\n\t\t\t\t\t\t\t| undefined;\n\t\t\t\t\t\treturn stored?.[actorIdField];\n\t\t\t\t\t})();\n\t\tif (ownerId === undefined) return false;\n\t\tif (ownerId === callerId) return true;\n\t\treturn canModerate !== undefined ? canModerate(ctx as Ctx) : false;\n\t};\n\n// ─── In-memory store ────────────────────────────────────────────────────────\n\n/**\n * Standard in-memory store for a pack table. Every row needs an `id: string`\n * (the table's primary key); the writer is upsert-by-id. Used by every\n * official pack as the default backing store.\n */\nexport type InMemoryStore<Row extends { id: string }> = {\n\treader: TableReader<CollectionContext>;\n\twriter: TableWriter<Row, CollectionContext, unknown>;\n\t/** Lookup by id — convenient for permission and mutation handlers. */\n\tgetById: (id: string) => Row | undefined;\n\t/** Direct read of the underlying Map for advanced use; treat as read-only. */\n\trows: Map<string, Row>;\n};\n\n/**\n * Build a fresh, isolated in-memory store. Each call gets its own Map, so\n * two pack instances on the same engine don't share state.\n *\n * @example\n * const store = config.store ?? createInMemoryStore<NotificationRow>();\n */\nexport const createInMemoryStore = <\n\tRow extends { id: string }\n>(): InMemoryStore<Row> => {\n\tconst rows = new Map<string, Row>();\n\treturn {\n\t\tgetById: (id) => rows.get(id),\n\t\treader: {\n\t\t\tall: () => [...rows.values()]\n\t\t},\n\t\trows,\n\t\twriter: {\n\t\t\tdelete: (row) => {\n\t\t\t\trows.delete((row as { id: string }).id);\n\t\t\t},\n\t\t\tinsert: (data) => {\n\t\t\t\trows.set(data.id, data);\n\t\t\t\treturn data;\n\t\t\t},\n\t\t\tupdate: (data) => {\n\t\t\t\tconst prior = rows.get(data.id);\n\t\t\t\tconst merged = { ...(prior ?? {}), ...data } as Row;\n\t\t\t\trows.set(data.id, merged);\n\t\t\t\treturn merged;\n\t\t\t}\n\t\t}\n\t};\n};\n"
+  ],
+  "mappings": ";;AAUA;AAAA;AAAA;AAgBO,IAAM,oBAAoB,MAGhC,CAAC,QAAS,IAA4B;AAWhC,IAAM,eAAe,CAC3B,YACA,KACA,YACY;AAAA,EACZ,MAAM,UAAU,WAAW,GAAU;AAAA,EACrC,IAAI,YAAY,aAAa,YAAY,IAAI;AAAA,IAC5C,MAAM,IAAI,kBAAkB,GAAG,uBAAuB;AAAA,EACvD;AAAA,EACA,OAAO;AAAA;AAkBD,IAAM,kBACZ,CACC,YACA,eAAuB,cAExB,CAAC,KAAc,QAA0B;AAAA,EACxC,MAAM,WAAW,WAAW,GAAU;AAAA,EACtC,IAAI,aAAa;AAAA,IAAW,OAAO;AAAA,EACnC,MAAM,WAAY,IAAgC;AAAA,EAClD,OAAO,aAAa;AAAA;AAyBf,IAAM,0BACZ,CAA0B,YAM1B,CAAC,KAAc,QAA0B;AAAA,EACxC;AAAA,IACC;AAAA,IACA;AAAA,IACA;AAAA,IACA,eAAe;AAAA,MACZ;AAAA,EACJ,MAAM,WAAW,WAAW,GAAU;AAAA,EACtC,IAAI,aAAa;AAAA,IAAW,OAAO;AAAA,EACnC,MAAM,WAAW;AAAA,EACjB,MAAM,UACL,SAAS,kBAAkB,YACxB,SAAS,iBACR,MAAM;AAAA,IACP,MAAM,KAAK,SAAS;AAAA,IACpB,IAAI,OAAO,OAAO;AAAA,MAAU;AAAA,IAC5B,MAAM,SAAS,MAAM,QAAQ,EAAE;AAAA,IAG/B,OAAO,SAAS;AAAA,KACd;AAAA,EACN,IAAI,YAAY;AAAA,IAAW,OAAO;AAAA,EAClC,IAAI,YAAY;AAAA,IAAU,OAAO;AAAA,EACjC,OAAO,gBAAgB,YAAY,YAAY,GAAU,IAAI;AAAA;AA0BxD,IAAM,sBAAsB,MAER;AAAA,EAC1B,MAAM,OAAO,IAAI;AAAA,EACjB,OAAO;AAAA,IACN,SAAS,CAAC,OAAO,KAAK,IAAI,EAAE;AAAA,IAC5B,QAAQ;AAAA,MACP,KAAK,MAAM,CAAC,GAAG,KAAK,OAAO,CAAC;AAAA,IAC7B;AAAA,IACA;AAAA,IACA,QAAQ;AAAA,MACP,QAAQ,CAAC,QAAQ;AAAA,QAChB,KAAK,OAAQ,IAAuB,EAAE;AAAA;AAAA,MAEvC,QAAQ,CAAC,SAAS;AAAA,QACjB,KAAK,IAAI,KAAK,IAAI,IAAI;AAAA,QACtB,OAAO;AAAA;AAAA,MAER,QAAQ,CAAC,SAAS;AAAA,QACjB,MAAM,QAAQ,KAAK,IAAI,KAAK,EAAE;AAAA,QAC9B,MAAM,SAAS,KAAM,SAAS,CAAC,MAAO,KAAK;AAAA,QAC3C,KAAK,IAAI,KAAK,IAAI,MAAM;AAAA,QACxB,OAAO;AAAA;AAAA,IAET;AAAA,EACD;AAAA;",
+  "debugId": "EA54D19BA095911A64756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@absolutejs/sync-pack-utils",
+	"version": "0.1.0",
+	"description": "Shared helpers for @absolutejs/sync packs — resolveActor, requireRowOwner/Moderator, createInMemoryStore, and other patterns extracted from the official packs",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/absolutejs/sync-packs.git",
+		"directory": "utils"
+	},
+	"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",
+		"utils",
+		"helpers"
+	],
+	"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"]
+}