anbaric-tsapi 1.8.1 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-tsapi",
-  "version": "1.8.1",
+  "version": "1.10.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/cloud/QueueMessage.ts

@@ -1,6 +1,7 @@
 type QueueMessage = {
     jobId : string,
     workflowId : string,
+    position? : number,
 };
 
 export type { QueueMessage }

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"