@ordinatio/entities 1.1.0 → 1.2.0

package/README.md

@@ -193,7 +193,7 @@ await app.entities.createNote({ entityType: 'client', entityId: 'client-123', co
 
 ### Tags Module (`@ordinatio/entities/tags`, experimental)
 
-Pure, zero-dependency helpers for tags, on their own subpath so a browser component can import them without pulling in the rest of the package (no Prisma, zod or Node modules): `tagNameKey` / `cleanTagName` / `checkTagName` (the case-insensitive identity of a name; **pinned to its first shipped behaviour** because apps store the key in a unique column), `TAG_COLORS` / `isTagColor` / `resolveTagColor`, `DEFAULT_TAG_LIMITS` (name length 40, 50 changes per save, 15 pinned, 500 per workspace: defaults, a store takes them as arguments), and the picker helpers `describeTagChanges`, `tagSetKey`, `rebaseSelection`, `mergeTagOptions`. The `./schemas` and `./errors` subpaths exist only in the workspace (source) exports map and are not part of the published package yet. A store interface, service and contract suite are planned for a later release on a separate server entry; until a second product has used them, the interface is experimental.
+Pure, zero-dependency helpers for tags, on their own subpath so a browser component can import them without pulling in the rest of the package (no Prisma, zod or Node modules): `tagNameKey` / `cleanTagName` / `checkTagName` (the case-insensitive identity of a name; **pinned to its first shipped behaviour** because apps store the key in a unique column), `TAG_COLORS` / `isTagColor` / `resolveTagColor`, `DEFAULT_TAG_LIMITS` (name length 40, 50 changes per save, 15 pinned, 500 per workspace: defaults, a store takes them as arguments), and the picker helpers `describeTagChanges`, `tagSetKey`, `rebaseSelection`, `mergeTagOptions`. The `./schemas` and `./errors` subpaths exist only in the workspace (source) exports map and are not part of the published package yet. On the separate server entry `@ordinatio/entities/tags/server` (EXPERIMENTAL until a second product has used it): the `TagStore` interface (built per workspace, so the package never sees a tenant id; atomic, typed, limit-aware operations), `createTagService(store, limits?)` (the tag rules over any store: validate and clean names and colours, create and find-or-create, rename/recolour/pin, remove, apply only the changes a user made to one item's tags, and read tags back sorted; every outcome a user can cause is a typed `{ ok: false, reason, ... }` result with the context an app needs for its message, and a store result it does not know throws; a store that throws is not caught, so an app that must never fail a page, such as a sidebar of pinned tags, wraps that one call itself; `pinned()` asks the store for the first `maxPinned` pinned tags, so make `listPinned` return them in a stable order such as by name), `planTagChanges`, an in-memory reference store (`createMemoryTagWorld`, `createMemoryTagHarness`) and the store contract suite `defineTagStoreContract` that any storage adapter must pass (framework-agnostic: pass your runner's `describe`/`it`/`expect`). Pin this package's exact version while the server entry is experimental: adding a required store method or a contract rule can break an adapter that passed before. The concurrency tests are meaningful only against a real store: run them against your database with a connection pool of at least 10. **Adapters and mappers must treat an unknown result `kind` or reason as an error**, never as success: adding a kind is a breaking change for an exhaustive switch.
 
 ### Contacts Module
 

package/dist/chunk-KPZRBM5J.mjs

@@ -0,0 +1,67 @@
+// src/tags/constants.ts
+var TAG_COLORS = ["neutral", "red", "amber", "green", "blue", "purple", "pink"];
+var DEFAULT_TAG_LIMITS = Object.freeze({
+  maxNameLength: 40,
+  maxChangesPerSave: 50,
+  maxPinned: 15,
+  maxPerWorkspace: 500
+});
+
+// src/tags/name.ts
+function cleanTagName(name) {
+  return name.trim().replace(/\s+/g, " ");
+}
+function tagNameKey(name) {
+  return cleanTagName(name).toLowerCase();
+}
+function checkTagName(name, maxLength = DEFAULT_TAG_LIMITS.maxNameLength) {
+  const cleaned = cleanTagName(name);
+  if (cleaned.length < 1) return { ok: false, reason: "empty", length: cleaned.length };
+  if (cleaned.length > maxLength) return { ok: false, reason: "too-long", length: cleaned.length };
+  return { ok: true, name: cleaned, key: tagNameKey(cleaned) };
+}
+function isTagColor(value) {
+  return typeof value === "string" && TAG_COLORS.includes(value);
+}
+function resolveTagColor(color) {
+  if (color === void 0) return { ok: true, color: "neutral" };
+  return isTagColor(color) ? { ok: true, color } : { ok: false };
+}
+
+// src/tags/changes.ts
+function describeTagChanges(before, after) {
+  return [
+    before.name !== after.name ? `renamed "${before.name}" to "${after.name}"` : "",
+    before.color !== after.color ? `changed its color to ${after.color}` : "",
+    before.pinned !== after.pinned ? after.pinned ? "pinned it to Bookmarks" : "unpinned it from Bookmarks" : ""
+  ].filter(Boolean);
+}
+function tagSetKey(ids) {
+  return [...new Set(ids)].sort().join(",");
+}
+function rebaseSelection(args) {
+  const initial = new Set(args.initial);
+  const selected = new Set(args.selected);
+  const userAdded = [...selected].filter((t) => !initial.has(t));
+  const userRemoved = new Set([...initial].filter((t) => !selected.has(t)));
+  const next = new Set([...args.server, ...userAdded].filter((t) => !userRemoved.has(t)));
+  return { initial: [...new Set(args.server)], selected: [...next] };
+}
+function mergeTagOptions(fresh, createdHere) {
+  const freshIds = new Set(fresh.map((t) => t.id));
+  return [...fresh, ...createdHere.filter((t) => !freshIds.has(t.id))].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export {
+  TAG_COLORS,
+  DEFAULT_TAG_LIMITS,
+  cleanTagName,
+  tagNameKey,
+  checkTagName,
+  isTagColor,
+  resolveTagColor,
+  describeTagChanges,
+  tagSetKey,
+  rebaseSelection,
+  mergeTagOptions
+};

package/dist/constants-DSRJ-l7Z.d.mts

@@ -0,0 +1,15 @@
+declare const TAG_COLORS: readonly ["neutral", "red", "amber", "green", "blue", "purple", "pink"];
+type TagColor = (typeof TAG_COLORS)[number];
+interface TagLimits {
+    /** Longest tag name, in characters, after cleaning. */
+    maxNameLength: number;
+    /** Upper bound on how many tags one save may add or remove: stops a crafted request sending thousands of ids into an IN query. */
+    maxChangesPerSave: number;
+    /** How many tags may be pinned (shown as bookmarks): pinning more is refused rather than silently ignored. */
+    maxPinned: number;
+    /** Per-workspace ceiling: forms load every tag, so an unbounded vocabulary would slow every form. */
+    maxPerWorkspace: number;
+}
+declare const DEFAULT_TAG_LIMITS: Readonly<TagLimits>;
+
+export { DEFAULT_TAG_LIMITS as D, type TagColor as T, TAG_COLORS as a, type TagLimits as b };

package/dist/tags/index.d.mts

@@ -1,16 +1,5 @@
-declare const TAG_COLORS: readonly ["neutral", "red", "amber", "green", "blue", "purple", "pink"];
-type TagColor = (typeof TAG_COLORS)[number];
-interface TagLimits {
-    /** Longest tag name, in characters, after cleaning. */
-    maxNameLength: number;
-    /** Upper bound on how many tags one save may add or remove: stops a crafted request sending thousands of ids into an IN query. */
-    maxChangesPerSave: number;
-    /** How many tags may be pinned (shown as bookmarks): pinning more is refused rather than silently ignored. */
-    maxPinned: number;
-    /** Per-workspace ceiling: forms load every tag, so an unbounded vocabulary would slow every form. */
-    maxPerWorkspace: number;
-}
-declare const DEFAULT_TAG_LIMITS: Readonly<TagLimits>;
+import { T as TagColor } from '../constants-DSRJ-l7Z.mjs';
+export { D as DEFAULT_TAG_LIMITS, a as TAG_COLORS, b as TagLimits } from '../constants-DSRJ-l7Z.mjs';
 
 /** Trims and collapses every run of whitespace (including tabs and no-break spaces) to one plain space. */
 declare function cleanTagName(name: string): string;
@@ -75,4 +64,4 @@ interface TagChoice {
  */
 declare function mergeTagOptions<T extends TagChoice>(fresh: readonly T[], createdHere: readonly T[]): T[];
 
-export { DEFAULT_TAG_LIMITS, type RebasedSelection, TAG_COLORS, type TagChoice, type TagColor, type TagLimits, type TagNameCheck, type TagSnapshot, checkTagName, cleanTagName, describeTagChanges, isTagColor, mergeTagOptions, rebaseSelection, resolveTagColor, tagNameKey, tagSetKey };
+export { type RebasedSelection, type TagChoice, TagColor, type TagNameCheck, type TagSnapshot, checkTagName, cleanTagName, describeTagChanges, isTagColor, mergeTagOptions, rebaseSelection, resolveTagColor, tagNameKey, tagSetKey };

package/dist/tags/index.mjs

@@ -1,56 +1,16 @@
-// src/tags/constants.ts
-var TAG_COLORS = ["neutral", "red", "amber", "green", "blue", "purple", "pink"];
-var DEFAULT_TAG_LIMITS = Object.freeze({
-  maxNameLength: 40,
-  maxChangesPerSave: 50,
-  maxPinned: 15,
-  maxPerWorkspace: 500
-});
-
-// src/tags/name.ts
-function cleanTagName(name) {
-  return name.trim().replace(/\s+/g, " ");
-}
-function tagNameKey(name) {
-  return cleanTagName(name).toLowerCase();
-}
-function checkTagName(name, maxLength = DEFAULT_TAG_LIMITS.maxNameLength) {
-  const cleaned = cleanTagName(name);
-  if (cleaned.length < 1) return { ok: false, reason: "empty", length: cleaned.length };
-  if (cleaned.length > maxLength) return { ok: false, reason: "too-long", length: cleaned.length };
-  return { ok: true, name: cleaned, key: tagNameKey(cleaned) };
-}
-function isTagColor(value) {
-  return typeof value === "string" && TAG_COLORS.includes(value);
-}
-function resolveTagColor(color) {
-  if (color === void 0) return { ok: true, color: "neutral" };
-  return isTagColor(color) ? { ok: true, color } : { ok: false };
-}
-
-// src/tags/changes.ts
-function describeTagChanges(before, after) {
-  return [
-    before.name !== after.name ? `renamed "${before.name}" to "${after.name}"` : "",
-    before.color !== after.color ? `changed its color to ${after.color}` : "",
-    before.pinned !== after.pinned ? after.pinned ? "pinned it to Bookmarks" : "unpinned it from Bookmarks" : ""
-  ].filter(Boolean);
-}
-function tagSetKey(ids) {
-  return [...new Set(ids)].sort().join(",");
-}
-function rebaseSelection(args) {
-  const initial = new Set(args.initial);
-  const selected = new Set(args.selected);
-  const userAdded = [...selected].filter((t) => !initial.has(t));
-  const userRemoved = new Set([...initial].filter((t) => !selected.has(t)));
-  const next = new Set([...args.server, ...userAdded].filter((t) => !userRemoved.has(t)));
-  return { initial: [...new Set(args.server)], selected: [...next] };
-}
-function mergeTagOptions(fresh, createdHere) {
-  const freshIds = new Set(fresh.map((t) => t.id));
-  return [...fresh, ...createdHere.filter((t) => !freshIds.has(t.id))].sort((a, b) => a.name.localeCompare(b.name));
-}
+import {
+  DEFAULT_TAG_LIMITS,
+  TAG_COLORS,
+  checkTagName,
+  cleanTagName,
+  describeTagChanges,
+  isTagColor,
+  mergeTagOptions,
+  rebaseSelection,
+  resolveTagColor,
+  tagNameKey,
+  tagSetKey
+} from "../chunk-KPZRBM5J.mjs";
 export {
   DEFAULT_TAG_LIMITS,
   TAG_COLORS,

package/dist/tags/server/index.d.mts

@@ -0,0 +1,282 @@
+import { b as TagLimits } from '../../constants-DSRJ-l7Z.mjs';
+
+/** The fields the rules need. An adapter may return a wider row (createdAt ...): the store is generic over it. */
+interface TagRecord {
+    id: string;
+    name: string;
+    /** The case-insensitive identity of the name (unique per workspace): see `tagNameKey` in `@ordinatio/entities/tags`. */
+    nameKey: string;
+    color: string;
+    pinned: boolean;
+}
+/** Named object types so a future limit is an additive field, not a signature change. */
+interface TagCreateLimits {
+    maxTags: number;
+}
+interface TagUpdateLimits {
+    maxPinned: number;
+}
+type TagCreateResult<T extends TagRecord> = {
+    kind: 'created';
+    tag: T;
+} | {
+    kind: 'duplicate';
+} | {
+    kind: 'limit';
+};
+interface TagUpdatePatch {
+    /** Name and key travel TOGETHER so they cannot disagree. */
+    rename?: {
+        name: string;
+        nameKey: string;
+    };
+    color?: string;
+    pinned?: boolean;
+}
+type TagUpdateResult<T extends TagRecord> = {
+    kind: 'updated';
+    before: T;
+    after: T;
+} | {
+    kind: 'notFound';
+} | {
+    kind: 'pinLimit';
+} | {
+    kind: 'duplicate';
+};
+type TagRemoveResult<T extends TagRecord> = {
+    kind: 'removed';
+    tag: T;
+} | {
+    kind: 'notFound';
+};
+interface TagLinkChange {
+    add: string[];
+    remove: string[];
+}
+type TagApplyResult = {
+    kind: 'applied';
+    added: string[];
+    removed: string[];
+    skipped: string[];
+} | {
+    kind: 'targetGone';
+} | {
+    kind: 'tagGone';
+};
+interface TagStore<T extends TagRecord = TagRecord, Target extends string = string> {
+    /** Every tag of the workspace. ORDER IS UNSPECIFIED: the service sorts. */
+    list(): Promise<T[]>;
+    /**
+     * Pinned tags only, at most `limit`, in ONE bounded query (an app may run this on every page). Order unspecified, but when more are pinned
+     * than `limit` the SAME ones should come back each time (for example by name), or the bookmarks would change from page to page.
+     */
+    listPinned(limit: number): Promise<T[]>;
+    /** The tags of THIS workspace among `ids`; foreign or deleted ids are simply absent. */
+    getMany(ids: string[]): Promise<T[]>;
+    findByKey(nameKey: string): Promise<T | null>;
+    get(id: string): Promise<T | null>;
+    /**
+     * ATOMIC: the limit is enforced together with the insert, so simultaneous creates can never overshoot it. Precedence: `limit` wins over
+     * `duplicate` (a duplicate name when the workspace is full is `limit`).
+     */
+    create(input: {
+        name: string;
+        nameKey: string;
+        color: string;
+    }, limits: TagCreateLimits): Promise<TagCreateResult<T>>;
+    /**
+     * ATOMIC. Precedence: `notFound`, then `pinLimit`, then `duplicate`. Pinning a tag that is ALREADY pinned never counts against the limit
+     * (the pinned flag is re-read under the lock); unpinning needs no limit. Renaming a tag to the same key it already has (a case change) is
+     * not a duplicate. An empty patch is a no-op that returns `updated` with `before` equal to `after`.
+     * `before` is read in the same transaction as the write, so `before`/`after` are consistent under concurrent edits.
+     */
+    update(id: string, patch: TagUpdatePatch, limits: TagUpdateLimits): Promise<TagUpdateResult<T>>;
+    /** The tag's links go with it. Ten parallel removes of one tag give exactly one `removed`. */
+    remove(id: string): Promise<TagRemoveResult<T>>;
+    targetExists(target: Target, targetId: string): Promise<boolean>;
+    /**
+     * One transaction. Frozen result shapes:
+     *  - `skipped` = ids in `add` that are NOT tags of this workspace at the START of the call. Ids in `remove` that are not this workspace's
+     *    tags are IGNORED silently (never reported, never touched). An `add` that is already linked is in neither `added` nor `skipped`.
+     *  - A tag that existed at the start but is gone when the write happens: `tagGone`, nothing applied. A target that vanished: `targetGone`.
+     *  - `added` / `removed` come from rows the database REALLY inserted / deleted, so concurrent saves never double-report one change.
+     * An id in BOTH `add` and `remove` is undefined behaviour: the service never sends it (`planTagChanges` drops it from `remove`).
+     * `actorId` is stored with each new link (who tagged it); it is opaque to this package.
+     */
+    applyLinks(target: Target, targetId: string, change: TagLinkChange, actorId: string): Promise<TagApplyResult>;
+    /** Tags on one target. Order unspecified. */
+    tagsForTarget(target: Target, targetId: string): Promise<T[]>;
+    /** Tags for many targets in ONE round trip. Only targets with at least one tag appear in the map. */
+    tagsForTargets(target: Target, targetIds: string[]): Promise<Map<string, T[]>>;
+    /**
+     * Items per tag per target type, for EVERY tag of the workspace (or only `ids`): a tag with no links appears with zero for every target
+     * type. One grouped query per target type in a real adapter, not one per tag. An EMPTY `ids` asks for nothing: it returns an empty map.
+     */
+    counts(ids?: string[]): Promise<Map<string, Record<Target, number>>>;
+}
+
+type TagChangePlan = {
+    ok: true;
+    change: TagLinkChange;
+} | {
+    ok: false;
+    reason: 'too-many-changes';
+    count: number;
+};
+/**
+ * An id in both lists stays ADDED (the user's last word is "keep it"): it is dropped from `remove`. The count that is capped is the number
+ * of distinct changes after that (adds plus removes).
+ */
+declare function planTagChanges(change: TagLinkChange, maxChanges: number): TagChangePlan;
+
+/** Why a call did not do what was asked, with the context an app needs for its message. */
+type TagFailure = {
+    reason: 'invalid-name';
+    problem: 'empty' | 'too-long';
+    length: number;
+} | {
+    reason: 'invalid-color';
+    color: string;
+} | {
+    reason: 'duplicate';
+} | {
+    reason: 'limit';
+} | {
+    reason: 'pin-limit';
+} | {
+    reason: 'not-found';
+} | {
+    reason: 'target-gone';
+} | {
+    reason: 'tag-gone';
+} | {
+    reason: 'too-many-changes';
+    count: number;
+};
+type TagResult<V> = ({
+    ok: true;
+} & V) | ({
+    ok: false;
+} & TagFailure);
+interface TagOption {
+    id: string;
+    name: string;
+    color: string;
+}
+interface TagService<T extends TagRecord, Target extends string> {
+    /** Every tag, sorted by name. */
+    list(): Promise<T[]>;
+    /** Just what a picker needs, sorted by name. */
+    options(): Promise<TagOption[]>;
+    /** Pinned tags (at most `maxPinned`), sorted by name. */
+    pinned(): Promise<T[]>;
+    get(id: string): Promise<TagResult<{
+        tag: T;
+    }>>;
+    create(input: {
+        name: string;
+        color?: string;
+    }): Promise<TagResult<{
+        tag: T;
+    }>>;
+    /** The existing tag when the name is already taken (any case), else a new one. */
+    findOrCreate(name: string): Promise<TagResult<{
+        tag: T;
+        created: boolean;
+    }>>;
+    update(id: string, input: {
+        name?: string;
+        color?: string;
+        pinned?: boolean;
+    }): Promise<TagResult<{
+        before: T;
+        after: T;
+    }>>;
+    remove(id: string): Promise<TagResult<{
+        tag: T;
+    }>>;
+    /** Applies ONLY what the user changed. An empty change succeeds without touching the store (not even to check the item exists). */
+    applyChanges(target: Target, targetId: string, change: {
+        add: string[];
+        remove: string[];
+    }, actorId: string): Promise<TagResult<{
+        added: string[];
+        removed: string[];
+        skipped: string[];
+    }>>;
+    forTarget(target: Target, targetId: string): Promise<TagResult<{
+        tags: T[];
+    }>>;
+    forTargets(target: Target, targetIds: string[]): Promise<Map<string, T[]>>;
+    counts(ids?: string[]): Promise<Map<string, Record<Target, number>>>;
+}
+declare function createTagService<T extends TagRecord, Target extends string>(store: TagStore<T, Target>, suppliedLimits?: TagLimits): TagService<T, Target>;
+
+interface TagContractRunner {
+    describe: (name: string, body: () => void) => void;
+    it: ((name: string, body: () => Promise<void>) => void) & {
+        skip?: (name: string, body: () => Promise<void>) => void;
+    };
+    expect: (value: unknown) => {
+        toBe(expected: unknown): void;
+        toEqual(expected: unknown): void;
+        toBeNull(): void;
+    };
+}
+interface TagStoreHarness<Target extends string = string> {
+    /** The taggable kinds under test. The suite REQUIRES at least three (it throws otherwise); four or more prove that a new kind needs no change to the logic. */
+    targetTypes: readonly Target[];
+    /** A fresh, empty workspace id. Every test uses its own, so tests never see each other's rows. */
+    newWorkspace(): Promise<string>;
+    /** The store for one workspace. Called repeatedly for the same id: it must give the same data. */
+    storeFor(workspace: string): TagStore<TagRecord, Target>;
+    /** Creates a real taggable thing (a person, a task ...) in the workspace and returns its id. */
+    addTarget(workspace: string, type: Target): Promise<string>;
+    /**
+     * OPTIONAL. Creates a target of `type` with exactly this id, so a person and a task can share one id (as they do when ids are per-table
+     * integers). Offer it if your storage allows; the tests that need it are skipped (or reported as skipped) without it.
+     */
+    addTargetWithId?(workspace: string, type: Target, id: string): Promise<string>;
+    /**
+     * Deletes it with everything that points at it. NOTE: the contract also passes ids that do not exist, such as 'missing', 'ghost-1' or
+     * 'nothing', for tags and targets: an adapter with uuid or integer id columns must answer them as "not found" instead of failing the cast.
+     */
+    removeTarget(workspace: string, type: Target, id: string): Promise<void>;
+    /**
+     * OPTIONAL test seam. Arms a ONE-SHOT hook that the next `applyLinks` runs after its existence checks and before its write, so a test can
+     * delete a tag or a target at exactly the dangerous moment. Without it the two delete-while-applying checks are shown as skipped when your
+     * runner has `it.skip`; if it does not, they run and fail, so supply the hook.
+     */
+    armBeforeLinkWrite?(hook: () => Promise<void>): void;
+    /** Removes everything the tests created. */
+    cleanup(): Promise<void>;
+}
+
+interface MemoryTagWorldOptions<Target extends string> {
+    targetTypes: readonly Target[];
+    /** Default true. False removes the one-at-a-time chain so races become visible (for proving the contract's concurrency tests). */
+    serialise?: boolean;
+}
+interface MemoryTagWorld<Target extends string> {
+    store(workspace: string): TagStore<TagRecord, Target>;
+    /** Registers a taggable thing (a person, a task ...) and returns its id. */
+    addTarget(workspace: string, type: Target, id?: string): string;
+    /** Removes a target and every link to it. */
+    removeTarget(workspace: string, type: Target, id: string): Promise<void>;
+    /** Arms a ONE-SHOT hook run by the next `applyLinks` IN THIS WORLD (any workspace) between its existence check and its write (to delete a tag or target mid-flight). */
+    armBeforeLinkWrite(hook: () => Promise<void>): void;
+    /** Who linked it (the `actorId` passed to `applyLinks`), or undefined when there is no such link. */
+    actorOf(workspace: string, type: Target, targetId: string, tagId: string): string | undefined;
+}
+declare function createMemoryTagWorld<Target extends string>(options: MemoryTagWorldOptions<Target>): MemoryTagWorld<Target>;
+/** The contract harness around a fresh in-memory world: what this package runs its own contract with, and a starting point for an app's fake. */
+declare function createMemoryTagHarness<Target extends string>(targetTypes: readonly Target[], options?: {
+    serialise?: boolean;
+}): TagStoreHarness<Target> & {
+    world: MemoryTagWorld<Target>;
+};
+
+declare function defineTagStoreContract<Target extends string>(api: TagContractRunner, harness: TagStoreHarness<Target>): void;
+
+export { type MemoryTagWorld, type MemoryTagWorldOptions, type TagApplyResult, type TagChangePlan, type TagContractRunner, type TagCreateLimits, type TagCreateResult, type TagFailure, type TagLinkChange, type TagOption, type TagRecord, type TagRemoveResult, type TagResult, type TagService, type TagStore, type TagStoreHarness, type TagUpdateLimits, type TagUpdatePatch, type TagUpdateResult, createMemoryTagHarness, createMemoryTagWorld, createTagService, defineTagStoreContract, planTagChanges };