anbaric-tsapi 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "anbaric-tsapi",
+  "version": "1.0.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",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/api/actions/Action.ts

@@ -0,0 +1,25 @@
+import {Actor} from "../actors/Actor";
+import {Job} from "../jobs/Job";
+
+type CodeRun = (job : Job) => Promise<Map<string, any>>;
+
+class Action {
+
+    readonly id : string;
+    name : string;
+    description : string;
+    actor : Actor;
+
+    constructor(name : string, actor : Actor, description : string = "", id : string = crypto.randomUUID()) {
+        this.name = name;
+        this.actor = actor;
+        this.description = description;
+        this.id = id;
+    }
+
+    predicate = (_job : Job) => true;
+    run : CodeRun = async (_job : Job) => new Map();
+
+}
+
+export { Action }

package/src/api/actors/Actor.ts

@@ -0,0 +1,11 @@
+type ActorType = "HUMAN" | "CODE" | "AGENT";
+
+interface Actor {
+
+    type : ActorType;
+    id : string;
+    role : string;
+
+}
+
+export type { Actor, ActorType }

package/src/api/cloud/QueueMessage.ts

@@ -0,0 +1,6 @@
+type QueueMessage = {
+    jobId : string,
+    workflowId : string,
+};
+
+export type { QueueMessage }

package/src/api/documents/JsonSchema.ts

@@ -0,0 +1,53 @@
+type JsonSchema = {
+    type? : "object" | "array" | "string" | "number" | "integer" | "boolean" | "null",
+    properties? : Record<string, JsonSchema>,
+    required? : Array<string>,
+    items? : JsonSchema,
+    enum? : Array<any>,
+};
+
+const jsonTypeOf = (value : any) : string => {
+    if (value === null) return "null";
+    if (Array.isArray(value)) return "array";
+    if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+    return typeof value;
+};
+
+const matchesType = (value : any, expected : string) : boolean => {
+    const actual = jsonTypeOf(value);
+    return expected === "number" ? actual === "number" || actual === "integer" : actual === expected;
+};
+
+const isPlainObject = (value : any) : boolean => jsonTypeOf(value) === "object";
+
+const validateDocument = (document : any, schema : JsonSchema, path : string = "$") : Array<string> => {
+    const violations : Array<string> = [];
+
+    if (schema.type && !matchesType(document, schema.type)) {
+        violations.push(`${path} should be ${schema.type} but was ${jsonTypeOf(document)}`);
+        return violations;
+    }
+
+    if (schema.enum && !schema.enum.some(allowed => JSON.stringify(allowed) === JSON.stringify(document))) {
+        violations.push(`${path} must be one of ${JSON.stringify(schema.enum)}`);
+    }
+
+    if (isPlainObject(document)) {
+        for (const key of schema.required ?? []) {
+            if (!(key in document)) violations.push(`${path}.${key} is required`);
+        }
+        for (const [key, propertySchema] of Object.entries(schema.properties ?? {})) {
+            if (key in document) violations.push(...validateDocument(document[key], propertySchema, `${path}.${key}`));
+        }
+    }
+
+    if (Array.isArray(document) && schema.items) {
+        document.forEach((item, index) =>
+            violations.push(...validateDocument(item, schema.items!, `${path}[${index}]`)));
+    }
+
+    return violations;
+};
+
+export { validateDocument };
+export type { JsonSchema };

package/src/api/documents/JsonStore.ts

@@ -0,0 +1,10 @@
+interface JsonStore {
+
+    save(id : string, document : any) : Promise<void>;
+    retrieve(id : string) : Promise<any>;
+    delete(id : string) : Promise<void>;
+    list(pageSize? : number, page? : number) : Promise<Array<any>>;
+
+}
+
+export { JsonStore }

package/src/api/jobs/Job.ts

@@ -0,0 +1,50 @@
+import {Transition} from "../transitions/Transition";
+import {JobTransition} from "./JobTransition";
+
+class Job {
+
+    readonly id : string;
+    private state: string;
+    properties : Map<string, any>;
+    readonly workflowId? : string;
+    readonly startedAt : Date;
+    readonly startedBy : string;
+    lastUpdated : Date;
+    readonly transitions : Array<JobTransition>;
+
+    constructor(id : string, properties : Map<string, any> = new Map(), initialState: string, workflowId? : string,
+                startedBy : string = "system", startedAt : Date = new Date(),
+                lastUpdated : Date = startedAt, transitions : Array<JobTransition> = []) {
+        this.id = id;
+        this.properties = properties;
+        this.state = initialState;
+        this.workflowId = workflowId;
+        this.startedBy = startedBy;
+        this.startedAt = startedAt;
+        this.lastUpdated = lastUpdated;
+        this.transitions = transitions;
+    }
+
+    private setState(stateId : string) : void {
+        this.state = stateId;
+    }
+
+    get stateId() : string | undefined {
+        return this.state;
+    }
+
+    transition(transition : Transition, actor : string = this.workflowId ?? "state-machine") : boolean {
+
+        if (transition.predicate(this)) {
+            this.transitions.push({ from: this.state, to: transition.to, actor });
+            this.setState(transition.to);
+            this.lastUpdated = new Date();
+            return true;
+        }
+
+        return false;
+    }
+
+}
+
+export { Job }

package/src/api/jobs/JobPersistence.ts

@@ -0,0 +1,13 @@
+import {Job} from "./Job";
+
+interface JobPersistence {
+
+    save(job : Job) : Promise<void>;
+    retrieve(id : string) : Promise<Job>;
+    delete(id : string) : Promise<void>;
+    list(pageSize? : number, page? : number) : Promise<Array<Job>>;
+    updateProperties(id : string, properties : Map<string, any>) : Promise<void>;
+
+}
+
+export { JobPersistence }

package/src/api/jobs/JobSerialization.ts

@@ -0,0 +1,35 @@
+import {Job} from "./Job";
+import {JobTransition} from "./JobTransition";
+
+type SerializedJob = {
+    id : string,
+    state : string,
+    properties : Record<string, any>,
+    workflowId? : string,
+    startedAt? : string,
+    startedBy? : string,
+    lastUpdated? : string,
+    transitions? : Array<JobTransition>,
+};
+
+const serializeJob = (job : Job) : SerializedJob => ({
+    id: job.id,
+    state: job.stateId!,
+    properties: Object.fromEntries(job.properties),
+    workflowId: job.workflowId,
+    startedAt: job.startedAt.toISOString(),
+    startedBy: job.startedBy,
+    lastUpdated: job.lastUpdated.toISOString(),
+    transitions: job.transitions,
+});
+
+const deserializeJob = (serialized : SerializedJob) : Job => {
+    const startedAt = serialized.startedAt ? new Date(serialized.startedAt) : new Date();
+    return new Job(serialized.id, new Map(Object.entries(serialized.properties)), serialized.state,
+        serialized.workflowId, serialized.startedBy ?? "system", startedAt,
+        serialized.lastUpdated ? new Date(serialized.lastUpdated) : startedAt,
+        serialized.transitions ?? []);
+};
+
+export { serializeJob, deserializeJob };
+export type { SerializedJob };

package/src/api/jobs/JobTransition.ts

@@ -0,0 +1,7 @@
+type JobTransition = {
+    from : string,
+    to : string,
+    actor : string,
+};
+
+export type { JobTransition }

package/src/api/jobs/PropertyDefinition.ts

@@ -0,0 +1,12 @@
+class PropertyDefinition {
+
+    id : string;
+    required : boolean = false;
+    validation : (arg0: any) => boolean = (value : any) => true;
+
+    constructor(id : string) {
+        this.id = id;
+    }
+}
+
+export { PropertyDefinition }

package/src/api/secrets/SecretStore.ts

@@ -0,0 +1,10 @@
+interface SecretStore {
+
+    save(name : string, value : string) : Promise<void>;
+    retrieve(name : string) : Promise<string>;
+    delete(name : string) : Promise<void>;
+    list() : Promise<Array<string>>;
+
+}
+
+export { SecretStore }

package/src/api/state-machine/Consumer.ts

@@ -0,0 +1,8 @@
+interface Consumer {
+
+    subscribe(workflowId : string, processJob : (jobId : string) => Promise<void>) : void;
+    cleanUp() : Promise<void>;
+
+}
+
+export { Consumer }

package/src/api/state-machine/Queue.ts

@@ -0,0 +1,22 @@
+import {QueueMessage} from "../cloud/QueueMessage";
+
+interface Queue {
+
+    enqueue(jobId : string, workflowId : string) : Promise<void>;
+    schedule(jobId : string, workflowId : string, due : Date) : Promise<void>;
+
+}
+
+interface Dequeue extends Queue {
+
+    dequeueSome() : Promise<Array<QueueMessage>>;
+
+}
+
+const Dequeue = {
+    supports(queue : Queue) : queue is Dequeue {
+        return "dequeueSome" in queue;
+    },
+};
+
+export { Queue, Dequeue }

package/src/api/states/State.ts

@@ -0,0 +1,22 @@
+import {Action} from "../actions/Action";
+import {Transition} from "../transitions/Transition";
+
+class State {
+
+    readonly id : string;
+    actions : Array<Action>;
+    transitions : Array<Transition>;
+
+    constructor(id : string, actions : Array<Action> = [], transitions : Array<Transition> = []) {
+        this.id = id;
+        this.actions = actions;
+        this.transitions = transitions;
+    }
+
+    subscribe(action : Action) : void {
+        this.actions.push(action);
+    }
+
+}
+
+export { State }

package/src/api/transitions/Transition.ts

@@ -0,0 +1,13 @@
+import {Job} from "../jobs/Job";
+
+class Transition {
+    to: string;
+    predicate: (job: Job) => boolean;
+
+    constructor(to: string, predicate: (job: Job) => boolean) {
+        this.to = to;
+        this.predicate = predicate;
+    }
+}
+
+export { Transition }

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./api/jobs/Job";
+export * from "./api/jobs/JobPersistence"
+export * from "./api/jobs/JobSerialization"
+export * from "./api/jobs/JobTransition"
+export * from "./api/jobs/PropertyDefinition"
+export * from "./api/states/State"
+export * from "./api/actions/Action"
+export * from "./api/transitions/Transition"
+export * from "./api/actors/Actor"
+export * from "./api/documents/JsonStore"
+export * from "./api/secrets/SecretStore"
+export * from "./api/documents/JsonSchema"
+export * from "./api/state-machine/Queue"
+export * from "./api/state-machine/Consumer"
+export * from "./api/cloud/QueueMessage"