@ordinatio/entities 1.1.0 → 1.3.0

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

@@ -0,0 +1,168 @@
+import { b as TagLinkChange, T as TagRecord, a as TagStore } from '../../types-C81I1Teg.mjs';
+export { c as TagApplyResult, d as TagCreateLimits, e as TagCreateResult, f as TagRemoveResult, g as TagUpdateLimits, h as TagUpdatePatch, i as TagUpdateResult } from '../../types-C81I1Teg.mjs';
+import { b as TagLimits } from '../../constants-DSRJ-l7Z.mjs';
+
+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 TagChangePlan, type TagContractRunner, type TagFailure, TagLinkChange, type TagOption, TagRecord, type TagResult, type TagService, TagStore, type TagStoreHarness, createMemoryTagHarness, createMemoryTagWorld, createTagService, defineTagStoreContract, planTagChanges };