bazis 0.130.0 → 0.132.0

package/core/workflow/definitions_module/code/defineProcess.ts

@@ -1,4 +1,4 @@
-import type { ProcessDocument } from "../../../../library/workflow";
+import type { LocalizedText, ProcessDocument } from "../../../../library/workflow";
 
 const CODE_PROCESS = Symbol.for("bazis/core/workflow/code-process");
 
@@ -6,8 +6,12 @@ const CODE_PROCESS = Symbol.for("bazis/core/workflow/code-process");
 export interface ProcessDefinition {
   /** The key it is started by: `^[a-z][a-z0-9_.-]{0,63}$`. */
   readonly key: string;
-  readonly title: string;
-  readonly description?: string | null;
+  readonly title: LocalizedText;
+  readonly description?: LocalizedText | null;
+  /** A path in the catalog: `Sales/Orders`. */
+  readonly folder?: string | null;
+  /** Whose process it is: an opaque id. */
+  readonly owner?: string | null;
   /** Days to keep completed and cancelled instances; omitted keeps them. */
   readonly retentionDays?: number | null;
   readonly document: ProcessDocument;
@@ -27,9 +31,11 @@ export interface CodeProcess extends ProcessDefinition {
  * export const OrderApprovalProcess = defineProcess({
  *   key: "order-approval",
  *   title: "Order approval",
- *   document: { schemaVersion: "bazis.workflow/v1", nodes: { … }, flows: { … } },
+ *   document: { schemaVersion: "bazis.workflow/v2", nodes: { … }, flows: { … } },
  * });
  * ```
+ *
+ * A document of version 1 goes through `upgradeDocument`.
  */
 export function defineProcess(definition: ProcessDefinition): CodeProcess {
   return Object.freeze({ ...definition, [CODE_PROCESS]: true as const });

package/core/workflow/definitions_module/events/Definitions.events.ts

@@ -0,0 +1,16 @@
+import { createEventToken } from "../../../kernel";
+import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
+
+export type ProcessChange = "created" | "updated" | "draftSaved" | "published" | "archived" | "restored";
+
+/** A process of the catalog changed, for the application's audit. Published after the commit. */
+export interface WorkflowProcessChanged {
+  readonly change: ProcessChange;
+  readonly key: string;
+  /** The version a `published` change made; otherwise `null`. */
+  readonly version: number | null;
+  readonly actor: WorkflowActor;
+  readonly request: WorkflowRequest | null;
+}
+
+export const WORKFLOW_PROCESS_CHANGED = createEventToken<WorkflowProcessChanged>("workflow.process-changed");

package/core/workflow/definitions_module/http/Processes.controller.ts

@@ -1,9 +1,11 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
-import { can } from "../../../access";
+import { can, type AccessObject } from "../../../access";
+import type { LocalizedText } from "../../../../library/workflow";
 import { Authorize, Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
-import { body, callerOf, optionalInteger, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
+import { buildListDocument } from "../../../../library/jsonapi";
+import { body, callerOf, defaultLanguage, filterOf, listQuery, optionalInteger, optionalString, optionalText, pagingOfList, param, requiredString, withTitleText } from "../../internal/http";
 import { WorkflowError } from "../../contracts/WorkflowError";
-import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
+import { IWorkflowDefinitions, type ProcessSummary } from "../services/IWorkflowDefinitions.service";
 
 /** The process catalog over HTTP (WORKFLOW-001 §3); rights are `workflow.processes.*` (WORKFLOW-002 §6.2). */
 @Controller("workflow")
@@ -13,11 +15,19 @@ export class ProcessesController {
   @Get("processes")
   @Authorize(can("workflow.processes.read"))
   async list(ctx: HttpContext) {
-    const { access } = await callerOf(ctx);
-    const archived = ctx.query("archived");
+    const { access, language } = await callerOf(ctx);
+    const list = listQuery(ctx, { filter: { archived: ["eq"], search: ["eq"], folder: ["eq"], owner: ["eq"] }, sort: ["key", "title", "folder", "createdAt", "updatedAt"] });
+    const archived = filterOf(list, "archived");
     if (archived !== undefined && archived !== "true" && archived !== "false") throw new WorkflowError("invalid_input", "archived must be true or false");
-    const page = await this.definitions.list({ ...pagingQuery(ctx), access: await access.filter("workflow.processes.read"), archived: archived === undefined ? undefined : archived === "true", search: optionalString(ctx.query("search"), "search") });
-    return { data: page.items, meta: { total: page.total } };
+    const page = await this.definitions.list({
+      ...pagingOfList(list),
+      access: await access.filter("workflow.processes.read"),
+      archived: archived === undefined ? undefined : archived === "true",
+      search: filterOf(list, "search"),
+      folder: filterOf(list, "folder"),
+      owner: filterOf(list, "owner"),
+    });
+    return buildListDocument(this.localized(page.items, language, ctx), list, page.total, { basePath: ctx.path });
   }
 
   @Post("processes")
@@ -25,22 +35,25 @@ export class ProcessesController {
   async create(ctx: HttpContext) {
     const request = await body(ctx);
     const key = requiredString(request.key, "key", 64);
-    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const folder = optionalString(request.folder, "folder", 500) ?? null;
+    const { actor, request: from, language } = await callerOf(ctx, "workflow.processes.manage", { process: key, folder });
     const process = await this.definitions.create({
       key,
-      title: requiredString(request.title, "title"),
-      description: optionalString(request.description, "description", 2000) ?? null,
+      title: optionalText(request.title) as LocalizedText,
+      description: optionalText(request.description) ?? null,
+      folder,
+      owner: optionalString(request.owner, "owner") ?? null,
       retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null,
-    }, actor);
-    return Created(`${ctx.path}/${process.key}`, process);
+    }, actor, { request: from });
+    return Created(`${ctx.path}/${process.key}`, withTitleText(process, language, defaultLanguage(ctx)));
   }
 
   @Get("processes/:key")
   @Authorize(can("workflow.processes.read"))
   async get(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await callerOf(ctx, "workflow.processes.read", { process: key });
-    return await this.definitions.get(key);
+    const { language } = await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
+    return withTitleText(await this.definitions.get(key), language, defaultLanguage(ctx));
   }
 
   @Patch("processes/:key")
@@ -48,14 +61,20 @@ export class ProcessesController {
   async update(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const { actor, request: from, language } = await callerOf(ctx, "workflow.processes.manage", await this.objectOf(key));
     if (request.archived !== undefined && typeof request.archived !== "boolean") throw new WorkflowError("invalid_input", "archived must be a boolean");
-    return await this.definitions.update(key, {
-      ...(request.title === undefined ? {} : { title: requiredString(request.title, "title") }),
-      ...(request.description === undefined ? {} : { description: optionalString(request.description, "description", 2000) ?? null }),
+    const folder = optionalString(request.folder, "folder", 500) ?? null;
+    // Moving a process needs the right in the folder it goes to as well.
+    if (request.folder !== undefined) await callerOf(ctx, "workflow.processes.manage", { process: key, folder });
+    const process = await this.definitions.update(key, {
+      ...(request.title === undefined ? {} : { title: optionalText(request.title) as LocalizedText }),
+      ...(request.description === undefined ? {} : { description: optionalText(request.description) ?? null }),
+      ...(request.folder === undefined ? {} : { folder }),
+      ...(request.owner === undefined ? {} : { owner: optionalString(request.owner, "owner") ?? null }),
       ...(request.retentionDays === undefined ? {} : { retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null }),
       ...(request.archived === undefined ? {} : { archived: request.archived as boolean }),
-    }, actor);
+    }, actor, { request: from });
+    return withTitleText(process, language, defaultLanguage(ctx));
   }
 
   @Put("processes/:key/draft")
@@ -63,16 +82,19 @@ export class ProcessesController {
   async saveDraft(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
-    return await this.definitions.saveDraft(key, request.document, actor);
+    const { actor, request: from, language } = await callerOf(ctx, "workflow.processes.manage", await this.objectOf(key));
+    const expected = optionalString(request.expected, "expected");
+    const expectedAt = expected === undefined ? undefined : new Date(expected);
+    if (expectedAt !== undefined && Number.isNaN(expectedAt.getTime())) throw new WorkflowError("invalid_input", "expected must be the draftUpdatedAt that was read");
+    return await this.definitions.saveDraft(key, request.document, actor, { request: from, language, ...(expectedAt === undefined ? {} : { expected: expectedAt }) });
   }
 
   @Post("processes/:key/publish")
   @Authorize(can("workflow.processes.publish"))
   async publish(ctx: HttpContext) {
     const key = param(ctx, "key");
-    const { actor } = await callerOf(ctx, "workflow.processes.publish", { process: key });
-    const version = await this.definitions.publish(key, actor);
+    const { actor, request, language } = await callerOf(ctx, "workflow.processes.publish", await this.objectOf(key));
+    const version = await this.definitions.publish(key, actor, { request, language });
     return Created(`${ctx.path.replace(/\/publish$/, "")}/versions/${version.version}`, version);
   }
 
@@ -80,7 +102,7 @@ export class ProcessesController {
   @Authorize(can("workflow.processes.read"))
   async versions(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await callerOf(ctx, "workflow.processes.read", { process: key });
+    await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
     return { data: await this.definitions.versions(key) };
   }
 
@@ -88,16 +110,41 @@ export class ProcessesController {
   @Authorize(can("workflow.processes.read"))
   async version(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await callerOf(ctx, "workflow.processes.read", { process: key });
+    await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
     const version = optionalInteger(param(ctx, "version"), "version");
     if (version === undefined) throw new WorkflowError("invalid_input", "version must be an integer");
     return await this.definitions.version(key, version);
   }
 
+  /** Checks a document without storing it: every finding, as a save and a publication would give them. */
+  @Post("validate")
+  @Authorize(can("workflow.processes.read"))
+  async validate(ctx: HttpContext) {
+    const request = await body(ctx);
+    const { actor, language } = await callerOf(ctx);
+    return { issues: await this.definitions.validate(request.document, { actor, language }) };
+  }
+
+  /** What a designer builds its forms from (WORKFLOW-002 §4.2). */
+  @Get("palette")
+  @Authorize(can("workflow.processes.read"))
+  async palette() {
+    return this.definitions.palette();
+  }
+
   @Get("tools")
   @Authorize(can("workflow.processes.read"))
   async tools() {
     return { data: this.definitions.tools() };
   }
+
+  /** A process as the object of a permission. */
+  private async objectOf(key: string): Promise<AccessObject> {
+    return { process: key, folder: await this.definitions.folderOf(key) };
+  }
+
+  private localized(items: readonly ProcessSummary[], language: string, ctx: HttpContext) {
+    return items.map((item) => withTitleText(item, language, defaultLanguage(ctx)));
+  }
 }
 contextOnlyController(ProcessesController);

package/core/workflow/definitions_module/model/Definitions.dbContext.ts

@@ -10,7 +10,7 @@ export class DefinitionsDbContext extends DbContext {
 /** The tables of the Definitions part: bazis creates and checks them in the application database. */
 export const definitionsStore = defineOrmOwnedStoreV1({
   contract: "bazis.orm-owned-store/v1",
-  storeKey: "bazis.workflow.definitions",
+  storeKey: "bazis.workflow.definitions.v2",
   formatVersion: 1,
-  ownedScope: { schema: "public", tablePrefix: "bazis_wf_def_" },
+  ownedScope: { schema: "public", tablePrefix: "bazis_wf2_def_" },
 });

package/core/workflow/definitions_module/model/WfProcess.model.ts

@@ -1,11 +1,12 @@
 import { Column, Entity, Index, UUID } from "../../../orm";
+import type { LocalizedText } from "../../../../library/workflow";
 
 /**
- * A process in the catalog: the key it is started by, its names, the draft a
- * designer edits and the retention of finished instances. Changes; the
+ * A process in the catalog: the key it is started by, its card (names, folder,
+ * owner), the draft a designer edits and the retention of finished instances. Changes; the
  * published versions ({@link WfVersion}) do not.
  */
-@Entity({ table: "bazis_wf_def_processes" })
+@Entity({ table: "bazis_wf2_def_processes" })
 export class WfProcess {
   @UUID({ version: "v7" })
   id = "";
@@ -14,11 +15,24 @@ export class WfProcess {
   @Column({ type: "text" })
   key = "";
 
+  @Column({ type: "json" })
+  title: LocalizedText = "";
+
+  /** Every text of `title`, the default language first: what a list searches and sorts by. */
   @Column({ type: "text" })
-  title = "";
+  titleText = "";
+
+  @Column({ type: "json", nullable: true })
+  description: LocalizedText | null = null;
+
+  /** A path, `Sales/Orders`: there is no folder entity. */
+  @Index()
+  @Column({ type: "text", nullable: true })
+  folder: string | null = null;
 
+  /** Whose process it is: an opaque id of the application. */
   @Column({ type: "text", nullable: true })
-  description: string | null = null;
+  owner: string | null = null;
 
   /** The draft document; kept with validation errors too. */
   @Column({ type: "json", nullable: true })

package/core/workflow/definitions_module/model/WfVersion.model.ts

@@ -4,7 +4,7 @@ import { WfProcess } from "./WfProcess.model";
 /** A published version of a process: an immutable snapshot of its document. */
 @ForeignKey(() => WfProcess, { properties: ["processId"], onDelete: "cascade" })
 @Index(["processId", "version"], { unique: true })
-@Entity({ table: "bazis_wf_def_versions" })
+@Entity({ table: "bazis_wf2_def_versions" })
 export class WfVersion {
   @UUID({ version: "v7" })
   id = "";

package/core/workflow/definitions_module/services/IWorkflowDefinitions.service.ts

@@ -1,13 +1,17 @@
 import type { AccessFilter } from "../../../access";
 import type { AgentToolContract } from "../../../agent";
-import type { ProcessDocument, ProcessIssue } from "../../../../library/workflow";
-import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { LocalizedText, ProcessDocument, ProcessIssue, ProcessPalette } from "../../../../library/workflow";
+import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
 
 export interface ProcessSummary {
   readonly key: string;
-  readonly title: string;
-  readonly description: string | null;
+  readonly title: LocalizedText;
+  readonly description: LocalizedText | null;
+  /** A path, `Sales/Orders`. */
+  readonly folder: string | null;
+  /** Whose process it is: an opaque id. */
+  readonly owner: string | null;
   readonly latestVersion: number | null;
   readonly retentionDays: number | null;
   readonly archived: boolean;
@@ -41,14 +45,18 @@ export interface VersionDetails extends VersionSummary {
 
 export interface CreateProcess {
   readonly key: string;
-  readonly title: string;
-  readonly description?: string | null;
+  readonly title: LocalizedText;
+  readonly description?: LocalizedText | null;
+  readonly folder?: string | null;
+  readonly owner?: string | null;
   readonly retentionDays?: number | null;
 }
 
 export interface UpdateProcess {
-  readonly title?: string;
-  readonly description?: string | null;
+  readonly title?: LocalizedText;
+  readonly description?: LocalizedText | null;
+  readonly folder?: string | null;
+  readonly owner?: string | null;
   readonly retentionDays?: number | null;
   readonly archived?: boolean;
 }
@@ -57,8 +65,29 @@ export interface ProcessListQuery extends WorkflowPaging {
   /** Which processes the caller may see, from `IAccess`; without it the calling code has decided. */
   readonly access?: AccessFilter;
   readonly archived?: boolean;
-  /** Part of the key or title, case-insensitive. */
+  /** Part of the key or a title in any language, case-insensitive. */
   readonly search?: string;
+  /** This folder and those below it. */
+  readonly folder?: string;
+  readonly owner?: string;
+}
+
+/** Who asks for a validation: it goes to the application's `WorkflowExtensions`. */
+export interface ValidateOptions {
+  readonly language?: string;
+  readonly actor?: WorkflowActor;
+}
+
+export interface SaveDraftOptions extends WorkflowAuditOptions, Pick<ValidateOptions, "language"> {
+  /** The `draftUpdatedAt` the caller read: another save since then is `conflict`. Without it the last save wins. */
+  readonly expected?: Date;
+}
+
+export interface SavedDraft {
+  /** Every validation finding: a draft is stored with errors too. */
+  readonly issues: readonly ProcessIssue[];
+  /** Goes to `expected` of the next save. */
+  readonly draftUpdatedAt: Date;
 }
 
 /**
@@ -69,16 +98,22 @@ export interface ProcessListQuery extends WorkflowPaging {
 export abstract class IWorkflowDefinitions {
   abstract list(query?: ProcessListQuery): Promise<WorkflowPage<ProcessSummary>>;
   abstract get(key: string): Promise<ProcessDetails>;
-  abstract create(process: CreateProcess, actor: WorkflowActor): Promise<ProcessDetails>;
+  /** The folder of a process, for a check of rights; `null` also for a process that does not exist. */
+  abstract folderOf(key: string): Promise<string | null>;
+  /** Every finding of a document, with the application's `extensions` checks; nothing is stored. */
+  abstract validate(document: unknown, options?: ValidateOptions): Promise<readonly ProcessIssue[]>;
+  /** What a designer builds its forms from: node kinds, functions, paths and Tools. */
+  abstract palette(): ProcessPalette;
+  abstract create(process: CreateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
   /** A process declared in code takes only `archived`; other fields give `conflict`. */
-  abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor): Promise<ProcessDetails>;
-  /** Stores the draft even with errors and returns every validation finding; `conflict` for a process declared in code. */
-  abstract saveDraft(key: string, document: unknown, actor: WorkflowActor): Promise<{ readonly issues: readonly ProcessIssue[] }>;
+  abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
+  /** Stores the draft even with errors; `conflict` for a process declared in code and when `expected` is out of date. */
+  abstract saveDraft(key: string, document: unknown, actor: WorkflowActor, options?: SaveDraftOptions): Promise<SavedDraft>;
   /**
    * Validates the draft and stores it as the next version; the same document
    * again returns the latest version. `conflict` for a process declared in code.
    */
-  abstract publish(key: string, actor: WorkflowActor): Promise<VersionDetails>;
+  abstract publish(key: string, actor: WorkflowActor, options?: WorkflowAuditOptions & Pick<ValidateOptions, "language">): Promise<VersionDetails>;
   abstract versions(key: string): Promise<readonly VersionSummary[]>;
   abstract version(key: string, version: number): Promise<VersionDetails>;
   /** The latest published version of a process that is not archived. */