@ordinatio/entities 1.1.0 → 1.3.0

package/dist/types-C81I1Teg.d.mts

@@ -0,0 +1,117 @@
+/** 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>>>;
+}
+
+export type { TagRecord as T, TagStore as a, TagLinkChange as b, TagApplyResult as c, TagCreateLimits as d, TagCreateResult as e, TagRemoveResult as f, TagUpdateLimits as g, TagUpdatePatch as h, TagUpdateResult as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ordinatio/entities",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": false,
   "license": "MIT",
   "description": "Entity knowledge, agent intelligence, notes, and contacts",
@@ -19,6 +19,16 @@
       "types": "./dist/tags/index.d.mts",
       "import": "./dist/tags/index.mjs",
       "default": "./dist/tags/index.mjs"
+    },
+    "./tags/server": {
+      "types": "./dist/tags/server/index.d.mts",
+      "import": "./dist/tags/server/index.mjs",
+      "default": "./dist/tags/server/index.mjs"
+    },
+    "./tags/prisma": {
+      "types": "./dist/tags/prisma/index.d.mts",
+      "import": "./dist/tags/prisma/index.mjs",
+      "default": "./dist/tags/prisma/index.mjs"
     }
   },
   "publishConfig": {
@@ -49,7 +59,7 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/tags/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/tags/index.ts src/tags/server/index.ts src/tags/prisma/index.ts --format esm --dts --clean",
     "test": "vitest",
     "test:run": "vitest run"
   }