@ordinatio/entities 1.0.4 → 1.1.0

package/README.md

@@ -191,6 +191,10 @@ await app.entities.createNote({ entityType: 'client', entityId: 'client-123', co
 | `getNotes(db, options)` | Query | List notes with cursor pagination |
 | `deleteNote(db, noteId, entityId)` | Mutation | Delete a note |
 
+### 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.
+
 ### Contacts Module
 
 | Function | Type | Description |

package/dist/tags/index.d.mts

@@ -0,0 +1,78 @@
+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>;
+
+/** Trims and collapses every run of whitespace (including tabs and no-break spaces) to one plain space. */
+declare function cleanTagName(name: string): string;
+/** The identity of a name inside one workspace: the cleaned name, lower-cased. Two names with the same key are the same tag. */
+declare function tagNameKey(name: string): string;
+type TagNameCheck = {
+    ok: true;
+    name: string;
+    key: string;
+} | {
+    ok: false;
+    reason: 'empty' | 'too-long';
+    length: number;
+};
+/** Cleans the name and checks its length (1 to `maxLength`, default 40, counted in UTF-16 code units like the stored value). */
+declare function checkTagName(name: string, maxLength?: number): TagNameCheck;
+declare function isTagColor(value: unknown): value is TagColor;
+/** No colour means the neutral one; a name that is not in the list is invalid. */
+declare function resolveTagColor(color: string | undefined): {
+    ok: true;
+    color: TagColor;
+} | {
+    ok: false;
+};
+
+interface TagSnapshot {
+    name: string;
+    color: string;
+    pinned: boolean;
+}
+/** One phrase per field that actually changed; empty when nothing did (so nothing is logged). */
+declare function describeTagChanges(before: TagSnapshot, after: TagSnapshot): string[];
+/** Order-independent identity of a set of tag ids. */
+declare function tagSetKey(ids: readonly string[]): string;
+/**
+ * The server's tag set for an item changed while the user had the picker open (their own save came back, or a teammate tagged the item).
+ * Keep the user's unsaved edits (what they added and removed relative to the OLD baseline), apply them on top of the NEW server set, and
+ * make the new server set the baseline. So nothing the user chose is lost, nothing a teammate added is stripped, and the next save's diff
+ * stays correct.
+ */
+interface RebasedSelection {
+    /** The new baseline: the server's current set, de-duplicated. */
+    initial: string[];
+    /** The user's unsaved choices applied on top of it. */
+    selected: string[];
+}
+declare function rebaseSelection(args: {
+    initial: readonly string[];
+    selected: readonly string[];
+    server: readonly string[];
+}): RebasedSelection;
+interface TagChoice {
+    id: string;
+    name: string;
+    color: string;
+}
+/**
+ * The tag list a picker shows: the server's current list (so renames, new tags and deletions by teammates show up), plus tags created in
+ * this very picker that the server list has not caught up with yet. Sorted by name with `localeCompare`, which follows the runtime's
+ * locale and ICU data, so a server and a browser can order accented or mixed-case names differently: do not rely on the order matching
+ * across runtimes.
+ */
+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 };

package/dist/tags/index.mjs

@@ -0,0 +1,66 @@
+// 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 {
+  DEFAULT_TAG_LIMITS,
+  TAG_COLORS,
+  checkTagName,
+  cleanTagName,
+  describeTagChanges,
+  isTagColor,
+  mergeTagOptions,
+  rebaseSelection,
+  resolveTagColor,
+  tagNameKey,
+  tagSetKey
+};

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "@ordinatio/entities",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "private": false,
   "license": "MIT",
   "description": "Entity knowledge, agent intelligence, notes, and contacts",
   "engines": {
     "node": ">=22.0.0"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./tags": {
+      "types": "./dist/tags/index.d.mts",
+      "import": "./dist/tags/index.mjs",
+      "default": "./dist/tags/index.mjs"
     }
   },
   "publishConfig": {
@@ -24,7 +30,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@ordinatio/errors": "1.0.0"
+    "@ordinatio/errors": "1.2.0"
   },
   "devDependencies": {
     "@ordinatio/core": "^1.0.0",
@@ -43,7 +49,7 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/tags/index.ts --format esm --dts --clean",
     "test": "vitest",
     "test:run": "vitest run"
   }