anbaric-tsapi 1.8.0 → 1.9.0

package/README.md

@@ -11,12 +11,10 @@ synchronous.
 
 ## Value classes
 
-**`Job`** — a unit of work moving through a workflow.
-`new Job(id, properties = new Map(), initialState, workflowId?, startedBy = "system", startedAt = new Date(), lastUpdated = startedAt, transitions = [])`.
-`stateId` is a getter; state only changes through
-`transition(transition, actor = workflowId ?? "state-machine")`, which
-records `{from, to, actor}` into `transitions` and bumps `lastUpdated` when
-the transition's predicate accepts the job.
+**`Job`** — a unit of work moving through a workflow. Immutable.
+`new Job(id, properties = new Map(), state, workflowId?, startedBy = "system", startedAt = new Date(), lastUpdated = startedAt)`.
+`state` is a readonly string; a job never changes in place — `JobPersistence.save`
+constructs a new `Job` at the target `state` and stamps `lastUpdated`.
 
 **`State`** — `new State(id, actions = [], transitions = [])`, plus
 `subscribe(action)` to add an action later.
@@ -27,7 +25,7 @@ accept) gates whether the action runs, and
 `run : (job) => Promise<Map<string, any>>` (defaults to an empty map)
 returns the property changes the action wants. `run` never mutates the job.
 
-**`Actor`** — an interface, pure identity: `{ type : "HUMAN" | "CODE" | "AGENT", id : string, role : string }`.
+**`Actor`** — an interface, pure identity: `{ type : "HUMAN" | "CODE" | "AGENT" | "SYSTEM", id : string, role : string }`.
 Concrete `Human`, `Code`, `Agent` classes live in `anbaric-state-machine`.
 
 **`Transition`** — `new Transition(to, predicate)`; the first accepting
@@ -37,18 +35,18 @@ transition in a state wins.
 `required : boolean` (default false) and `validation : (value) => boolean`
 (default accept).
 
-**`JobTransition`** — `{ from : string, to : string, actor : string }`.
-
 **Serialization** — `serializeJob(job) : SerializedJob` and
 `deserializeJob(serialized) : Job` define the wire shape used by the cloud
 clients and platform (dates as ISO strings, properties as a plain object).
 
 ## Contracts
 
-**`JobPersistence`** — `save(job)`, `retrieve(id)` (throws
-`No job found with id "x"`), `delete(id)`, `list(pageSize = 100, page = 0)`,
-`updateProperties(id, properties)` (merge; implementations stamp
-`lastUpdated`).
+**`JobPersistence`** — an abstract class taking an `Auditor`; every method takes
+the acting `Actor` and audits before deferring to an abstract `…Internal`.
+`create(actor, job)`, `save(actor, changeDescription, job, properties?, state?)`
+(applies the property/state change and stamps `lastUpdated`),
+`retrieve(id, actor)` (throws `No job found with id "x"`), `delete(id, actor)`,
+`list(actor, pageSize?, page?)`.
 
 **`Queue`** — `enqueue(jobId, workflowId)`, `schedule(jobId, workflowId, due)`.
 **`Dequeue extends Queue`** adds `dequeueSome() : Promise<Array<QueueMessage>>`;
@@ -58,10 +56,15 @@ Delivery is at-least-once: consumers must tolerate redelivery.
 **`Consumer`** — `subscribe(workflowId, processJob)` routes deliveries for
 one workflow to a callback; `cleanUp()` releases resources.
 
-**`JsonStore`** — `save(id, document)`, `retrieve(id)`, `delete(id)`,
-`list()`; implementations validate against a `JsonSchema` when one is given.
+**`JsonStore`** — abstract, `Auditor`-backed and actor-audited like
+`JobPersistence`: `create(actor, id, document)`,
+`save(actor, changeDescription, id, document)`, `retrieve(id, actor)`,
+`delete(id, actor)`, `list(actor, pageSize?, page?)` (returns the document
+values, not ids); implementations validate against a `JsonSchema` when one is given.
 
-**`SecretStore`** — `save(name, value)`, `retrieve(name)`, `list()`.
+**`SecretStore`** — abstract, `Auditor`-backed: `create(actor, name, value)`,
+`save(actor, changeDescription, name, value)`, `retrieve(name, actor)`,
+`delete(name, actor)`, `list(actor)`. Secret values never appear in audit details.
 
 **`QueueMessage`** — `{ jobId, workflowId }`; part of the platform's private
 wire protocol (in `api/cloud/`), exported because `Dequeue` returns it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-tsapi",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "These are the shared libraries - types, classes, etc - that both the public state-machine and hosting services share",
   "license": "MIT",
   "author": "chris@anbaric.ai",

package/src/api/auditing/Auditor.ts

@@ -1,19 +1,13 @@
 import {Actor} from "../actors/Actor";
 
-enum AuditInteraction {
-    CREATE = "CREATE",
-    UPDATE_PROPERTIES = "UPDATE_PROPERTIES",
-    CHANGE_STATE = "CHANGE_STATE",
-    DELETE = "DELETE",
-    READ = "READ",
-    LIST = "LIST",
-}
-
+/* Records an interaction with a resource. The interaction is one or more plain
+   strings chosen by the persistence class that calls it - the auditor itself
+   defines no vocabulary. */
 interface Auditor {
 
-    audit(resourceType : string, resourceId : string, actor : Actor, interaction : AuditInteraction[],
+    audit(resourceType : string, resourceId : string, actor : Actor, interaction : Array<string>,
           description : string, details : any) : Promise<void>;
 
 }
 
-export { AuditInteraction, Auditor }
+export { Auditor }

package/src/api/auditing/NoOpAuditor.ts

@@ -1,12 +1,12 @@
 import {Actor} from "../actors/Actor";
-import {AuditInteraction, Auditor} from "./Auditor";
+import {Auditor} from "./Auditor";
 
 /* An auditor that records nothing. Used by the persistence instances that sit
    behind the HTTP API, where the app-facing store on the other side has
    already audited the interaction. */
 class NoOpAuditor implements Auditor {
 
-    async audit(_resourceType : string, _resourceId : string, _actor : Actor, _interaction : AuditInteraction[],
+    async audit(_resourceType : string, _resourceId : string, _actor : Actor, _interaction : Array<string>,
                 _description : string, _details : any) : Promise<void> {
     }
 

package/src/api/cloud/AuditRecord.ts

@@ -1,12 +1,10 @@
-import {AuditInteraction} from "../auditing/Auditor";
-
 type AuditRecord = {
     id? : string,
     resourceType : string,
     resourceId : string,
     actorId : string,
     actorType : string,
-    interaction : AuditInteraction[],
+    interaction : Array<string>,
     description : string,
     details : any,
     at? : string,

package/src/api/documents/JsonStore.ts

@@ -1,5 +1,5 @@
 import {Actor} from "../actors/Actor";
-import {AuditInteraction, Auditor} from "../auditing/Auditor";
+import {Auditor} from "../auditing/Auditor";
 
 /* A schema-validated JSON document store that audits every interaction, keyed
    by collection and id. Public methods audit then defer to ...Internal. */
@@ -9,27 +9,27 @@ abstract class JsonStore {
     }
 
     async create(actor : Actor, id : string, document : any) : Promise<void> {
-        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [AuditInteraction.CREATE], "Document created", document);
+        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.CREATE], "Document created", document);
         await this.saveInternal(id, document);
     }
 
     async save(actor : Actor, changeDescription : string, id : string, document : any) : Promise<void> {
-        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [AuditInteraction.UPDATE_PROPERTIES], changeDescription, document);
+        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.SAVE], changeDescription, document);
         await this.saveInternal(id, document);
     }
 
     async retrieve(id : string, actor : Actor) : Promise<any> {
-        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [AuditInteraction.READ], "", null);
+        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.READ], "", null);
         return this.retrieveInternal(id);
     }
 
     async delete(id : string, actor : Actor) : Promise<void> {
-        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [AuditInteraction.DELETE], "", null);
+        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.DELETE], "", null);
         await this.deleteInternal(id);
     }
 
     async list(actor : Actor, pageSize? : number, page? : number) : Promise<Array<any>> {
-        await this.auditor.audit("document", `${this.collection}/*`, actor, [AuditInteraction.LIST], "", null);
+        await this.auditor.audit("document", `${this.collection}/*`, actor, [JsonStore.Interaction.LIST], "", null);
         return this.listInternal(pageSize, page);
     }
 
@@ -40,4 +40,16 @@ abstract class JsonStore {
 
 }
 
+namespace JsonStore {
+
+    export enum Interaction {
+        CREATE = "CREATE",
+        SAVE = "SAVE",
+        READ = "READ",
+        DELETE = "DELETE",
+        LIST = "LIST",
+    }
+
+}
+
 export { JsonStore }

package/src/api/jobs/JobPersistence.ts

@@ -1,7 +1,6 @@
 import {Actor} from "../actors/Actor";
-import {AuditInteraction, Auditor} from "../auditing/Auditor";
+import {Auditor} from "../auditing/Auditor";
 import {Job} from "./Job";
-import {SystemActor} from "../actors/SystemActor";
 
 /* Persists jobs and audits every interaction. Public methods record the
    interaction against the injected auditor and then defer to the abstract
@@ -14,7 +13,7 @@ abstract class JobPersistence {
     async create(actor : Actor,
                job : Job) : Promise<void> {
 
-        await this.auditor.audit("job", job.id, actor, [AuditInteraction.CREATE], "Job created", job);
+        await this.auditor.audit("job", job.id, actor, [JobPersistence.Interaction.CREATE], "Job created", job);
 
         this.saveInternal(job);
     }
@@ -30,9 +29,9 @@ abstract class JobPersistence {
             state: state ? {from : job.state, to : state} : undefined
         }
 
-        const interaction = [];
-        if (properties) interaction.push(AuditInteraction.UPDATE_PROPERTIES);
-        if (state) interaction.push(AuditInteraction.CHANGE_STATE);
+        const interaction : Array<string> = [];
+        if (properties) interaction.push(JobPersistence.Interaction.UPDATE_PROPERTIES);
+        if (state) interaction.push(JobPersistence.Interaction.CHANGE_STATE);
 
         await this.auditor.audit("job", job.id, actor, interaction, changeDescription, change);
 
@@ -67,17 +66,17 @@ abstract class JobPersistence {
     }
 
     async retrieve(id : string, actor : Actor) : Promise<Job> {
-        await this.auditor.audit("job", id, actor, [AuditInteraction.READ], "", null);
+        await this.auditor.audit("job", id, actor, [JobPersistence.Interaction.READ], "", null);
         return this.retrieveInternal(id);
     }
 
     async delete(id : string, actor : Actor) : Promise<void> {
-        await this.auditor.audit("job", id, actor, [AuditInteraction.DELETE], "", null);
+        await this.auditor.audit("job", id, actor, [JobPersistence.Interaction.DELETE], "", null);
         await this.deleteInternal(id);
     }
 
     async list(actor : Actor, pageSize? : number, page? : number) : Promise<Array<Job>> {
-        await this.auditor.audit("job", "*", actor, [AuditInteraction.LIST], "", null);
+        await this.auditor.audit("job", "*", actor, [JobPersistence.Interaction.LIST], "", null);
         return this.listInternal(pageSize, page);
     }
 
@@ -88,4 +87,17 @@ abstract class JobPersistence {
 
 }
 
+namespace JobPersistence {
+
+    export enum Interaction {
+        CREATE = "CREATE",
+        UPDATE_PROPERTIES = "UPDATE_PROPERTIES",
+        CHANGE_STATE = "CHANGE_STATE",
+        DELETE = "DELETE",
+        READ = "READ",
+        LIST = "LIST",
+    }
+
+}
+
 export { JobPersistence }

package/src/api/secrets/SecretStore.ts

@@ -1,5 +1,5 @@
 import {Actor} from "../actors/Actor";
-import {AuditInteraction, Auditor} from "../auditing/Auditor";
+import {Auditor} from "../auditing/Auditor";
 
 /* Stores named secrets and audits every interaction. The secret value is
    never included in an audit record. Public methods audit then defer to the
@@ -10,27 +10,27 @@ abstract class SecretStore {
     }
 
     async create(actor : Actor, name : string, value : string) : Promise<void> {
-        await this.auditor.audit("secret", name, actor, [AuditInteraction.CREATE], "Secret created", null);
+        await this.auditor.audit("secret", name, actor, [SecretStore.Interaction.CREATE], "Secret created", null);
         await this.saveInternal(name, value);
     }
 
     async save(actor : Actor, changeDescription : string, name : string, value : string) : Promise<void> {
-        await this.auditor.audit("secret", name, actor, [AuditInteraction.UPDATE_PROPERTIES], changeDescription, null);
+        await this.auditor.audit("secret", name, actor, [SecretStore.Interaction.SAVE], changeDescription, null);
         await this.saveInternal(name, value);
     }
 
     async retrieve(name : string, actor : Actor) : Promise<string> {
-        await this.auditor.audit("secret", name, actor, [AuditInteraction.READ], "", null);
+        await this.auditor.audit("secret", name, actor, [SecretStore.Interaction.READ], "", null);
         return this.retrieveInternal(name);
     }
 
     async delete(name : string, actor : Actor) : Promise<void> {
-        await this.auditor.audit("secret", name, actor, [AuditInteraction.DELETE], "", null);
+        await this.auditor.audit("secret", name, actor, [SecretStore.Interaction.DELETE], "", null);
         await this.deleteInternal(name);
     }
 
     async list(actor : Actor) : Promise<Array<string>> {
-        await this.auditor.audit("secret", "*", actor, [AuditInteraction.LIST], "", null);
+        await this.auditor.audit("secret", "*", actor, [SecretStore.Interaction.LIST], "", null);
         return this.listInternal();
     }
 
@@ -41,4 +41,16 @@ abstract class SecretStore {
 
 }
 
+namespace SecretStore {
+
+    export enum Interaction {
+        CREATE = "CREATE",
+        SAVE = "SAVE",
+        READ = "READ",
+        DELETE = "DELETE",
+        LIST = "LIST",
+    }
+
+}
+
 export { SecretStore }

package/src/api/sql/SqlStore.ts

@@ -0,0 +1,40 @@
+import {Actor} from "../actors/Actor";
+import {Auditor} from "../auditing/Auditor";
+
+/* A relational (SQL) store for application data. Public methods audit the
+   interaction then defer to the abstract ...Internal. `query` returns rows;
+   `execute` runs a statement and returns the number of affected rows. The
+   backing engine (SQLite locally, PostgreSQL in the cloud) is chosen by the
+   factory; SQL placeholder syntax differs between them (see the docs). */
+abstract class SqlStore {
+
+    constructor(protected auditor : Auditor) {
+    }
+
+    async query(actor : Actor, sql : string, parameters : Array<any> = []) : Promise<Array<Record<string, any>>> {
+        await this.auditor.audit("sql", "*", actor, [SqlStore.Interaction.QUERY], sql, null);
+        return this.queryInternal(sql, parameters);
+    }
+
+    async execute(actor : Actor, sql : string, parameters : Array<any> = []) : Promise<number> {
+        await this.auditor.audit("sql", "*", actor, [SqlStore.Interaction.EXECUTE], sql, null);
+        return this.executeInternal(sql, parameters);
+    }
+
+    abstract close() : Promise<void>;
+
+    protected abstract queryInternal(sql : string, parameters : Array<any>) : Promise<Array<Record<string, any>>>;
+    protected abstract executeInternal(sql : string, parameters : Array<any>) : Promise<number>;
+
+}
+
+namespace SqlStore {
+
+    export enum Interaction {
+        QUERY = "QUERY",
+        EXECUTE = "EXECUTE",
+    }
+
+}
+
+export { SqlStore }

package/src/index.ts

@@ -15,6 +15,7 @@ export * from "./api/actors/Actor"
 export * from "./api/actors/SystemActor"
 export * from "./api/documents/JsonStore"
 export * from "./api/secrets/SecretStore"
+export * from "./api/sql/SqlStore"
 export * from "./api/documents/JsonSchema"
 export * from "./api/state-machine/Queue"
 export * from "./api/state-machine/Consumer"