@nocobase/app-plugin-projects 0.0.0-stage → 0.1.0-beta.2

package/dist/server/kernel/ids.d.ts

@@ -0,0 +1,9 @@
+/** String ids for every record this plugin creates. */
+export interface IdSource {
+    next(): string;
+}
+/** Over the application's id generator (`idGeneratorToken` of `@nocobase/app-server/id-generator`). */
+export declare function createIdSource(generator: {
+    generateString(): string;
+}): IdSource;
+//# sourceMappingURL=ids.d.ts.map

package/dist/server/kernel/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../server/kernel/ids.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,SAAS,EAAE;IACxC,cAAc,IAAI,MAAM,CAAC;CAC1B,GAAG,QAAQ,CAEX"}

package/dist/server/kernel/ids.js

@@ -0,0 +1,5 @@
+/** Over the application's id generator (`idGeneratorToken` of `@nocobase/app-server/id-generator`). */
+export function createIdSource(generator) {
+    return { next: () => generator.generateString() };
+}
+//# sourceMappingURL=ids.js.map

package/dist/server/kernel/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../server/kernel/ids.ts"],"names":[],"mappings":"AAKA,uGAAuG;AACvG,MAAM,UAAU,cAAc,CAAC,SAE9B;IACC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,cAAc,EAAE,EAAE,CAAC;AACpD,CAAC"}

package/dist/server/kernel/kinds.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The kinds of principal the plugin knows (`shared/kinds.ts`): `user` and `system` built in, more registered through
+ * `projectsKindsToken` before the plugin's services are first used. A kind says how its ids are named, whether it may
+ * execute issues and be mentioned, and which moves a workflow may let it make.
+ */
+import type { DatabaseConnection } from '@nocobase/db';
+import type { BusinessKey } from '../../shared/access.js';
+import type { MentionCandidate, MentionRef } from '../../shared/comments.js';
+import type { StatusCategory } from '../../shared/issues.js';
+import { type ExecutorCandidate, type KindInfo, type KindTitle, type NameText } from '../../shared/kinds.js';
+import type { UserDirectory } from './users.js';
+import type { IssueWorkHandler } from './work.js';
+/** What a kind that may execute issues answers. */
+export interface ExecutorDirectory {
+    /** 400 unless `id` exists, may execute issues, and `userId` may give it work. */
+    require(conn: DatabaseConnection, id: string, userId: string): Promise<void>;
+    /** Whether an issue owned by `ownerUserId` may keep `id` as its executor. */
+    canKeep(conn: DatabaseConnection, id: string, ownerUserId: string): Promise<boolean>;
+    /** The ids `userId` may give work to, for an executor picker; a kind without it is not offered there. */
+    candidates?(conn: DatabaseConnection, userId: string): Promise<string[]>;
+    /** Names and state of `ids` for an executor picker or a board: whether one can take work now, and how busy it is. */
+    describe?(conn: DatabaseConnection, ids: readonly string[]): Promise<ExecutorDescription[]>;
+}
+export interface ExecutorDescription {
+    readonly id: string;
+    readonly name: string;
+    /** Its name in the viewer's language, when it has one. */
+    readonly nameText?: NameText;
+    /** Something can run its work now (for an agent: a fitting runner is online). */
+    readonly online?: boolean;
+    /** Work it is doing or has queued. */
+    readonly busy?: number;
+}
+/** What a kind that may be mentioned (`mention://<key>/<id>`) answers. */
+export interface MentionDirectory {
+    /** Candidates for the `@` list, best first; `issueId` names the issue being written about, if any. */
+    candidates(conn: DatabaseConnection, input: {
+        readonly userId: string;
+        readonly issueId: string | null;
+        readonly q: string;
+        readonly limit: number;
+    }): Promise<MentionCandidate[]>;
+    /**
+     * Whether `userId` may mention `id` (an agent the caller may not give work to, say). Allowed when left out. A note
+     * (`/note`) starts no work, which a kind may take into account.
+     */
+    mayMention?(conn: DatabaseConnection, id: string, input: {
+        readonly userId: string;
+        readonly note: boolean;
+    }): Promise<boolean>;
+}
+export interface PrincipalKind {
+    /** `^[a-z][a-z0-9_]{1,31}$`; `user` and `system` are taken. */
+    readonly key: string;
+    readonly title?: KindTitle;
+    /** Display names by id; unknown ids are left out. */
+    names?(conn: DatabaseConnection, ids: readonly string[]): Promise<Map<string, string>>;
+    readonly executor?: ExecutorDirectory;
+    /** Present when the kind may be mentioned. */
+    readonly mention?: MentionDirectory;
+    /** Whether a workflow may let this kind move an issue into a status of `category`. Every category by default. */
+    mayEnter?(category: StatusCategory): boolean;
+    /** Whether a workflow may let this kind move an issue to "any status". True by default. */
+    readonly mayTargetAny?: boolean;
+    /** What the kind does when issues it executes or is named in change (`kernel/work.ts`). */
+    readonly work?: IssueWorkHandler;
+    /**
+     * The business actions a principal of this kind may be granted at most, such as the ones an agent may be configured
+     * with; what it may do is always within what the person it acts for may do.
+     */
+    readonly actions?: readonly BusinessKey[];
+}
+export interface KindRegistry {
+    /** Registers a kind; returns what unregisters it. */
+    add(kind: PrincipalKind): () => void;
+    get(key: string): PrincipalKind | undefined;
+    has(key: string): boolean;
+    /** Every kind, built-in ones first, then in registration order. */
+    list(): readonly PrincipalKind[];
+    /** What the browser is told. */
+    info(): KindInfo[];
+    /** Names of ids of one kind; an unknown kind names nobody. */
+    names(conn: DatabaseConnection, key: string, ids: Iterable<string | null | undefined>): Promise<Map<string, string>>;
+    /** Names of principals of any kinds, looked up kind by kind: `name(type, id)` is null for an unknown one. */
+    nameAll(conn: DatabaseConnection, refs: Iterable<{
+        readonly type: string | null;
+        readonly id: string | null;
+    }>): Promise<(type: string | null, id: string | null) => string | null>;
+    /** The `@` list: each mentionable kind's candidates, other kinds before people, at most `limit`. */
+    mentionCandidates(conn: DatabaseConnection, input: {
+        readonly userId: string;
+        readonly issueId: string | null;
+        readonly q: string;
+        readonly limit: number;
+    }): Promise<MentionCandidate[]>;
+    /** 403 `MENTION_FORBIDDEN` when a kind refuses one of `refs`; mentions of unknown kinds are ignored. */
+    requireMentions(conn: DatabaseConnection, refs: readonly MentionRef[], input: {
+        readonly userId: string;
+        readonly note: boolean;
+    }): Promise<void>;
+    /**
+     * The executors of other kinds `userId` may give work to, for a picker: each kind that lists its candidates, in
+     * registration order, described when the kind can say whether one can take work now.
+     */
+    executorCandidates(conn: DatabaseConnection, userId: string): Promise<ExecutorCandidate[]>;
+    /** 400 `INVALID_EXECUTOR` unless `kind` may execute issues and `id` is one `userId` may give work to. */
+    requireExecutor(conn: DatabaseConnection, kind: string, id: string, userId: string): Promise<void>;
+}
+export declare function createKindRegistry(users: UserDirectory): KindRegistry;
+//# sourceMappingURL=kinds.d.ts.map

package/dist/server/kernel/kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.d.ts","sourceRoot":"","sources":["../../../server/kernel/kinds.ts"],"names":[],"mappings":"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"}

package/dist/server/kernel/kinds.js

@@ -0,0 +1,145 @@
+import { BUILTIN_KINDS, SYSTEM_KIND, USER_KIND, } from '../../shared/kinds.js';
+import { forbidden, invalid } from './errors.js';
+const KEY = /^[a-z][a-z0-9_]{1,31}$/u;
+export function createKindRegistry(users) {
+    const builtIn = [
+        {
+            key: USER_KIND,
+            names: (conn, ids) => users.names(conn, ids),
+            mention: {
+                async candidates(conn, { q, limit }) {
+                    const needle = q.trim().toLowerCase();
+                    return (await users.listActive(conn))
+                        .filter((user) => !needle ||
+                        user.name.toLowerCase().includes(needle) ||
+                        (user.email ?? '').toLowerCase().includes(needle))
+                        .slice(0, limit)
+                        .map((user) => ({
+                        kind: USER_KIND,
+                        id: user.id,
+                        name: user.name,
+                        ...(user.email ? { hint: user.email } : {}),
+                    }));
+                },
+            },
+            executor: {
+                async require(conn, id) {
+                    if (!(await users.isPerson(conn, id)))
+                        throw invalid('INVALID_EXECUTOR', 'The executor is not an active user.');
+                },
+                canKeep: () => Promise.resolve(true),
+            },
+        },
+        { key: SYSTEM_KIND },
+    ];
+    const added = new Map();
+    const all = () => [...builtIn, ...added.values()];
+    const get = (key) => all().find((kind) => kind.key === key);
+    return {
+        add(kind) {
+            if (!KEY.test(kind.key))
+                throw new TypeError(`Kind ${kind.key} must match ${String(KEY)}.`);
+            if (BUILTIN_KINDS.includes(kind.key) || added.has(kind.key))
+                throw new TypeError(`Kind ${kind.key} is registered already.`);
+            added.set(kind.key, kind);
+            return () => {
+                if (added.get(kind.key) === kind)
+                    added.delete(kind.key);
+            };
+        },
+        get,
+        has: (key) => get(key) !== undefined,
+        list: all,
+        info: () => all().map((kind) => ({
+            key: kind.key,
+            title: kind.title ?? null,
+            executor: kind.executor !== undefined,
+            mentionable: kind.mention !== undefined,
+        })),
+        async names(conn, key, ids) {
+            const wanted = [
+                ...new Set([...ids].filter((id) => Boolean(id))),
+            ];
+            const kind = get(key);
+            if (!kind?.names || wanted.length === 0)
+                return new Map();
+            return kind.names(conn, wanted);
+        },
+        async nameAll(conn, refs) {
+            const byKind = new Map();
+            for (const ref of refs) {
+                if (!ref.type || !ref.id)
+                    continue;
+                const ids = byKind.get(ref.type) ?? new Set();
+                ids.add(ref.id);
+                byKind.set(ref.type, ids);
+            }
+            const names = new Map(await Promise.all([...byKind].map(async ([key, ids]) => [key, await this.names(conn, key, ids)])));
+            return (type, id) => (type && id ? names.get(type)?.get(id) : undefined) ?? null;
+        },
+        async mentionCandidates(conn, input) {
+            // Other kinds first, people last, as the old `@` list put agents first.
+            const kinds = all().filter((kind) => kind.mention);
+            const ordered = [
+                ...kinds.filter((kind) => kind.key !== USER_KIND),
+                ...kinds.filter((kind) => kind.key === USER_KIND),
+            ];
+            const result = [];
+            for (const kind of ordered) {
+                if (result.length >= input.limit)
+                    break;
+                const found = await kind.mention.candidates(conn, {
+                    ...input,
+                    limit: input.limit - result.length,
+                });
+                result.push(...found.slice(0, input.limit - result.length));
+            }
+            return result;
+        },
+        async requireMentions(conn, refs, input) {
+            for (const ref of refs) {
+                const mention = get(ref.kind)?.mention;
+                if (mention?.mayMention &&
+                    !(await mention.mayMention(conn, ref.id, input)))
+                    throw forbidden(`You may not mention ${ref.kind} ${ref.id}.`, 'MENTION_FORBIDDEN');
+            }
+        },
+        async executorCandidates(conn, userId) {
+            const result = [];
+            for (const kind of all()) {
+                const executor = kind.executor;
+                if (!executor?.candidates)
+                    continue;
+                const ids = await executor.candidates(conn, userId);
+                if (ids.length === 0)
+                    continue;
+                if (executor.describe) {
+                    for (const found of await executor.describe(conn, ids))
+                        result.push({
+                            type: kind.key,
+                            id: found.id,
+                            name: found.name,
+                            ...(found.nameText ? { nameText: found.nameText } : {}),
+                            ...(found.online === undefined ? {} : { online: found.online }),
+                            ...(found.busy === undefined ? {} : { busy: found.busy }),
+                        });
+                    continue;
+                }
+                const names = await this.names(conn, kind.key, ids);
+                for (const id of ids)
+                    result.push({ type: kind.key, id, name: names.get(id) ?? id });
+            }
+            return result;
+        },
+        async requireExecutor(conn, key, id, userId) {
+            const executor = get(key)?.executor;
+            if (!executor)
+                throw invalid('INVALID_EXECUTOR', `executor.type must be one of ${all()
+                    .filter((kind) => kind.executor)
+                    .map((kind) => kind.key)
+                    .join(', ')}.`);
+            await executor.require(conn, id, userId);
+        },
+    };
+}
+//# sourceMappingURL=kinds.js.map

package/dist/server/kernel/kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.js","sourceRoot":"","sources":["../../../server/kernel/kinds.ts"],"names":[],"mappings":"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"}

package/dist/server/kernel/mentions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mention markup in Markdown text (descriptions and comments): `[@Name](mention://<kind>/<id>)` names a principal of
+ * a kind (`kernel/kinds.ts`), such as `mention://user/<userId>` for a member. The name is display text only; the id
+ * decides who is meant.
+ */
+import type { MentionRef } from '../../shared/comments.js';
+/** Every principal mentioned, of any kind, deduplicated in order of first appearance. */
+export declare function mentions(text: string): MentionRef[];
+/** The ids mentioned of one kind, deduplicated in order of first appearance. */
+export declare function mentioned(text: string, kind: string): string[];
+/** Principals mentioned in `after` but not in `before`. */
+export declare function newMentions(before: string, after: string): MentionRef[];
+/** A note starts with `/note`: it is read like a comment but starts no work. */
+export declare function isNote(text: string): boolean;
+/** Plain text for a notice: mentions as `@Name`, without the `/note` prefix, whitespace collapsed, cut at `max`. */
+export declare function excerpt(text: string, max: number): string;
+//# sourceMappingURL=mentions.d.ts.map

package/dist/server/kernel/mentions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.d.ts","sourceRoot":"","sources":["../../../server/kernel/mentions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAM3D,yFAAyF;AACzF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAWnD;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI9D;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CAGvE;AAED,gFAAgF;AAChF,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED,oHAAoH;AACpH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOzD"}

package/dist/server/kernel/mentions.js

@@ -0,0 +1,42 @@
+const MENTION = /\[@([^\]\n]*)\]\(mention:\/\/([a-z][a-z0-9_]{1,31})\/([A-Za-z0-9_.@-]+)\)/gu;
+const NOTE = /^\s*\/note(?:\s|$)/u;
+/** Every principal mentioned, of any kind, deduplicated in order of first appearance. */
+export function mentions(text) {
+    const seen = new Set();
+    const refs = [];
+    for (const [, , kind, id] of text.matchAll(MENTION)) {
+        if (!kind || !id)
+            continue;
+        const key = `${kind}/${id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        refs.push({ kind, id });
+    }
+    return refs;
+}
+/** The ids mentioned of one kind, deduplicated in order of first appearance. */
+export function mentioned(text, kind) {
+    return mentions(text)
+        .filter((ref) => ref.kind === kind)
+        .map((ref) => ref.id);
+}
+/** Principals mentioned in `after` but not in `before`. */
+export function newMentions(before, after) {
+    const old = new Set(mentions(before).map((ref) => `${ref.kind}/${ref.id}`));
+    return mentions(after).filter((ref) => !old.has(`${ref.kind}/${ref.id}`));
+}
+/** A note starts with `/note`: it is read like a comment but starts no work. */
+export function isNote(text) {
+    return NOTE.test(text);
+}
+/** Plain text for a notice: mentions as `@Name`, without the `/note` prefix, whitespace collapsed, cut at `max`. */
+export function excerpt(text, max) {
+    const plain = text
+        .replace(MENTION, (_, name) => `@${name}`)
+        .replace(NOTE, '')
+        .replace(/\s+/gu, ' ')
+        .trim();
+    return plain.length > max ? `${plain.slice(0, max - 1)}…` : plain;
+}
+//# sourceMappingURL=mentions.js.map

package/dist/server/kernel/mentions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.js","sourceRoot":"","sources":["../../../server/kernel/mentions.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,GACX,6EAA6E,CAAC;AAChF,MAAM,IAAI,GAAG,qBAAqB,CAAC;AAEnC,yFAAyF;AACzF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAiB,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,EAAE,AAAD,EAAG,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE;YAAE,SAAS;QAC3B,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAY;IAClD,OAAO,QAAQ,CAAC,IAAI,CAAC;SAClB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC;SAClC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC1B,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,KAAa;IACvD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5E,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,oHAAoH;AACpH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,GAAW;IAC/C,MAAM,KAAK,GAAG,IAAI;SACf,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;SACjD,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;SACjB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,IAAI,EAAE,CAAC;IACV,OAAO,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;AACpE,CAAC"}

package/dist/server/kernel/pagination.d.ts

@@ -0,0 +1,14 @@
+export type CursorFields = Readonly<Record<string, string | number | null>>;
+export declare function encodeCursor(fields: CursorFields): string;
+export declare function decodeCursor(cursor: string): CursorFields;
+/** A page size within [1, max]; absent → `fallback`. */
+export declare function pageLimit(value: number | null | undefined, fallback: number, max: number): number;
+/**
+ * One page from a query that was asked for `limit + 1` rows: the extra row only says there is a next page, whose
+ * cursor is the last kept row's sort fields.
+ */
+export declare function pageOf<T>(rows: readonly T[], limit: number, cursorOf: (row: T) => CursorFields): {
+    readonly rows: T[];
+    readonly nextCursor: string | null;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/server/kernel/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../server/kernel/pagination.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;AAE5E,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEzD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAWzD;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,YAAY,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAU5D"}

package/dist/server/kernel/pagination.js

@@ -0,0 +1,42 @@
+/**
+ * Opaque page cursors. The Repository pages by the sort fields of the last row it returned (`RepositoryCursor`); the
+ * API hands clients that row's sort fields as a base64url token, so clients never build or read one.
+ */
+import { invalid } from './errors.js';
+export function encodeCursor(fields) {
+    return Buffer.from(JSON.stringify(fields)).toString('base64url');
+}
+export function decodeCursor(cursor) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            return value;
+    }
+    catch {
+        // Falls through to the error below.
+    }
+    throw invalid('INVALID_PAGE_TOKEN', 'pageToken is not valid.');
+}
+/** A page size within [1, max]; absent → `fallback`. */
+export function pageLimit(value, fallback, max) {
+    if (value === null || value === undefined)
+        return fallback;
+    if (!Number.isInteger(value))
+        throw invalid('INVALID_QUERY', 'limit must be an integer.');
+    return Math.min(Math.max(value, 1), max);
+}
+/**
+ * One page from a query that was asked for `limit + 1` rows: the extra row only says there is a next page, whose
+ * cursor is the last kept row's sort fields.
+ */
+export function pageOf(rows, limit, cursorOf) {
+    const kept = rows.slice(0, limit);
+    const last = kept.at(-1);
+    return {
+        rows: kept,
+        nextCursor: rows.length > limit && last !== undefined
+            ? encodeCursor(cursorOf(last))
+            : null,
+    };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/server/kernel/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../server/kernel/pagination.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAItC,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAC/B,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAClD,CAAC;QACF,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAC7D,OAAO,KAAqB,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,oCAAoC;IACtC,CAAC;IACD,MAAM,OAAO,CAAC,oBAAoB,EAAE,yBAAyB,CAAC,CAAC;AACjE,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,SAAS,CACvB,KAAgC,EAChC,QAAgB,EAChB,GAAW;IAEX,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;QAC1B,MAAM,OAAO,CAAC,eAAe,EAAE,2BAA2B,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CACpB,IAAkB,EAClB,KAAa,EACb,QAAkC;IAElC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,OAAO;QACL,IAAI,EAAE,IAAI;QACV,UAAU,EACR,IAAI,CAAC,MAAM,GAAG,KAAK,IAAI,IAAI,KAAK,SAAS;YACvC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC9B,CAAC,CAAC,IAAI;KACX,CAAC;AACJ,CAAC"}

package/dist/server/kernel/tx.d.ts

@@ -0,0 +1,37 @@
+import type { DatabaseConnection, DatabaseManager } from '@nocobase/db';
+import type { DomainEvent, DomainEventBus } from './events.js';
+export interface Tx {
+    readonly conn: DatabaseConnection;
+    emit(event: DomainEvent): void;
+    /**
+     * The unit always rolls back (a plan's rehearsal): whatever runs in it reports what it would do and must start
+     * nothing outside the database. Its events are dropped.
+     */
+    readonly rehearsal?: boolean;
+}
+export type BeforeCommitHook = (tx: Tx, events: readonly DomainEvent[]) => Promise<void>;
+export interface TxRunner {
+    /**
+     * Runs `fn` in a transaction. With `outer`, `fn` joins that unit of work instead, and its events are published when
+     * the outermost transaction commits.
+     */
+    run<T>(fn: (tx: Tx) => Promise<T>, outer?: Tx): Promise<T>;
+    /** The connection for reads outside a transaction. */
+    read(): DatabaseConnection;
+    /** Registers a hook; returns what removes it. */
+    beforeCommit(hook: BeforeCommitHook): () => void;
+    /**
+     * Runs `fn` as one unit of work that every `run` inside it joins. With `rehearse`, the unit always rolls back and
+     * answers what `fn` returned; nothing it emits is published. Units do not nest.
+     */
+    unit<T>(fn: (tx: Tx) => Promise<T>, options?: {
+        readonly rehearse?: boolean;
+    }): Promise<T>;
+    /**
+     * Runs `fn` in a savepoint of `tx`: when it throws, only its own writes roll back and its events are dropped. Inside
+     * a unit, the services `fn` calls join the savepoint.
+     */
+    savepoint<T>(tx: Tx, fn: (tx: Tx) => Promise<T>): Promise<T>;
+}
+export declare function createTxRunner(database: Pick<DatabaseManager, 'transaction' | 'connection'>, bus: Pick<DomainEventBus, 'emit'>): TxRunner;
+//# sourceMappingURL=tx.d.ts.map

package/dist/server/kernel/tx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx.d.ts","sourceRoot":"","sources":["../../../server/kernel/tx.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAExE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE/D,MAAM,WAAW,EAAE;IACjB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,SAAS,WAAW,EAAE,KAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3D,sDAAsD;IACtD,IAAI,IAAI,kBAAkB,CAAC;IAC3B,iDAAiD;IACjD,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAAC;IACjD;;;OAGG;IACH,IAAI,CAAC,CAAC,EACJ,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GACxC,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9D;AAWD,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,GAAG,YAAY,CAAC,EAC7D,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAChC,QAAQ,CA8EV"}

package/dist/server/kernel/tx.js

@@ -0,0 +1,109 @@
+/**
+ * Units of work. A transaction collects the domain events its writes emit and publishes them only after it commits, so
+ * a listener never sees a change that was rolled back.
+ *
+ * Hooks registered with `beforeCommit` see those events while the transaction is still open and may write in it: what
+ * they write commits or rolls back with the change that caused it (the inbox, for example, turns events into items
+ * this way). Events a hook emits are handed to the hooks again, for a bounded number of rounds.
+ *
+ * A unit (`unit`) makes every service call inside it join one transaction without passing it along: the plan engine
+ * runs several services' writes as one change that commits or rolls back together. Inside a unit, `run` without
+ * `outer` joins the unit (or the savepoint `savepoint` opened), and `read` answers its connection. A rehearsing unit
+ * (`rehearse: true`) always rolls back, drops the events its writes emit, runs no commit hooks, and says so on its
+ * `Tx` (`rehearsal`), so a trigger can answer what it would start without queuing anything.
+ *
+ * Thin stand-in: the database layer's `transaction()` has no commit hooks of its own. Use them once it does.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Thrown inside a rehearsing unit to roll it back. */
+class Rollback extends Error {
+    value;
+    constructor(value) {
+        super('Rehearsal rolled back.');
+        this.value = value;
+    }
+}
+const MAX_HOOK_ROUNDS = 5;
+export function createTxRunner(database, bus) {
+    const hooks = new Set();
+    // The unit (or its savepoint) the current call runs in, if any.
+    const ambient = new AsyncLocalStorage();
+    async function runHooks(tx, pending) {
+        let handled = 0;
+        for (let round = 0; hooks.size > 0 && handled < pending.length && round < MAX_HOOK_ROUNDS; round += 1) {
+            const batch = pending.slice(handled);
+            handled = pending.length;
+            for (const hook of hooks)
+                await hook(tx, batch);
+        }
+    }
+    return {
+        async run(fn, outer) {
+            if (outer)
+                return fn(outer);
+            const joined = ambient.getStore();
+            if (joined)
+                return fn(joined);
+            const pending = [];
+            const result = await database.transaction(async (conn) => {
+                const tx = { conn, emit: (event) => pending.push(event) };
+                const value = await fn(tx);
+                await runHooks(tx, pending);
+                return value;
+            });
+            for (const event of pending)
+                bus.emit(event);
+            return result;
+        },
+        read: () => ambient.getStore()?.conn ?? database.connection(),
+        beforeCommit(hook) {
+            hooks.add(hook);
+            return () => {
+                hooks.delete(hook);
+            };
+        },
+        async unit(fn, options = {}) {
+            if (ambient.getStore())
+                throw new Error('Units of work do not nest.');
+            if (options.rehearse) {
+                try {
+                    await database.transaction(async (conn) => {
+                        const tx = { conn, emit: () => undefined, rehearsal: true };
+                        throw new Rollback(await ambient.run(tx, () => fn(tx)));
+                    });
+                }
+                catch (error) {
+                    if (error instanceof Rollback)
+                        return error.value;
+                    throw error;
+                }
+                throw new Error('A rehearsal did not roll back.');
+            }
+            const pending = [];
+            const result = await database.transaction(async (conn) => {
+                const tx = { conn, emit: (event) => pending.push(event) };
+                const value = await ambient.run(tx, () => fn(tx));
+                await runHooks(tx, pending);
+                return value;
+            });
+            for (const event of pending)
+                bus.emit(event);
+            return result;
+        },
+        async savepoint(tx, fn) {
+            const buffered = [];
+            const result = await tx.conn.transaction((conn) => {
+                const inner = {
+                    conn,
+                    emit: (event) => buffered.push(event),
+                    ...(tx.rehearsal ? { rehearsal: true } : {}),
+                };
+                return ambient.run(inner, () => fn(inner));
+            });
+            for (const event of buffered)
+                tx.emit(event);
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=tx.js.map

package/dist/server/kernel/tx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx.js","sourceRoot":"","sources":["../../../server/kernel/tx.ts"],"names":[],"mappings":"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"}