@highstate/backend 0.7.2 → 0.7.3

package/src/project/abstractions.ts

@@ -0,0 +1,89 @@
+import type { InstanceModel } from "@highstate/contract"
+import type { HubModel, HubModelPatch, InstanceModelPatch } from "../shared"
+
+export type ProjectModel = {
+  instances: InstanceModel[]
+  hubs: HubModel[]
+}
+
+export interface ProjectBackend {
+  /**
+   * List the ids of the available projects.
+   */
+  getProjectIds(): Promise<string[]>
+
+  /**
+   * Get the instances and hubs of the project.
+   *
+   * @param projectId The ID of the project.
+   */
+  getProject(projectId: string, signal?: AbortSignal): Promise<ProjectModel>
+
+  /**
+   * Create an empty project.
+   *
+   * @param projectId The ID of the project.
+   */
+  createProject(projectId: string): Promise<void>
+
+  /**
+   * Create the instance of the project.
+   *
+   * @param projectId The ID of the project.
+   * @param instance The instance to update.
+   */
+  createInstance(projectId: string, instance: InstanceModel): Promise<InstanceModel>
+
+  /**
+   * Rename the instance of the project.
+   * Changes its id and updates all references to the instance.
+   * Potentially dangerous, but safe when the instance is not yet created.
+   */
+  renameInstance(projectId: string, instanceId: string, newName: string): Promise<InstanceModel>
+
+  /**
+   * Patches the instance of the project.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceId The ID of the instance to update.
+   * @param patch The patch to apply to the instance.
+   */
+  updateInstance(
+    projectId: string,
+    instanceId: string,
+    patch: InstanceModelPatch,
+  ): Promise<InstanceModel>
+
+  /**
+   * Delete the instance of the project.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceId The ID of the instance to delete.
+   */
+  deleteInstance(projectId: string, instanceId: string): Promise<void>
+
+  /**
+   * Create a hub in the project.
+   *
+   * @param projectId The ID of the project.
+   * @param hub The hub to create.
+   */
+  createHub(projectId: string, hub: HubModel): Promise<HubModel>
+
+  /**
+   * Patches the hub of the project.
+   *
+   * @param projectId The ID of the project.
+   * @param hubId The ID of the hub to update.
+   * @param patch The patch to apply to the hub.
+   */
+  updateHub(projectId: string, hubId: string, patch: HubModelPatch): Promise<HubModel>
+
+  /**
+   * Delete the hub of the project.
+   *
+   * @param projectId The ID of the project.
+   * @param hubId The ID of the hub to delete.
+   */
+  deleteHub(projectId: string, hubId: string): Promise<void>
+}

package/src/project/factory.ts

@@ -0,0 +1,11 @@
+import { z } from "zod"
+import { localProjectBackendConfig, LocalProjectBackend } from "./local"
+
+export const projectBackendConfig = z.object({
+  HIGHSTATE_BACKEND_PROJECT_TYPE: z.enum(["local"]).default("local"),
+  ...localProjectBackendConfig.shape,
+})
+
+export function createProjectBackend(config: z.infer<typeof projectBackendConfig>) {
+  return LocalProjectBackend.create(config)
+}

package/src/project/index.ts

@@ -0,0 +1,4 @@
+export * from "./abstractions"
+export * from "./factory"
+export * from "./lock"
+export * from "./manager"

package/src/project/local.ts

@@ -0,0 +1,412 @@
+import type { ProjectBackend, ProjectModel } from "./abstractions"
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises"
+import { resolve } from "node:path"
+import { z } from "zod"
+import {
+  getInstanceId,
+  type HubInput,
+  type InstanceInput,
+  type InstanceModel,
+} from "@highstate/contract"
+import {
+  type HubModel,
+  type HubModelPatch,
+  hubModelSchema,
+  type InstanceModelPatch,
+  instanceModelSchema,
+} from "../shared"
+import { resolveMainLocalProject } from "../common"
+
+export const localProjectBackendConfig = z.object({
+  HIGHSTATE_BACKEND_PROJECT_PROJECTS_DIR: z.string().optional(),
+})
+
+const projectModelSchema = z.object({
+  instances: z.record(instanceModelSchema),
+  hubs: z.record(hubModelSchema),
+})
+
+/**
+ * A project backend that stores the projects locally on disk.
+ *
+ * By default, the projects are stored in the `projects` directory near the "package.json" file.
+ */
+export class LocalProjectBackend implements ProjectBackend {
+  constructor(private readonly projectsDir: string) {}
+
+  async getProjectIds(): Promise<string[]> {
+    try {
+      const files = await readdir(this.projectsDir)
+
+      return files.filter(file => file.endsWith(".json")).map(file => file.replace(/\.json$/, ""))
+    } catch (error) {
+      throw new Error("Failed to get project names", { cause: error })
+    }
+  }
+
+  async getProject(projectId: string): Promise<ProjectModel> {
+    try {
+      const project = await this.loadProject(projectId)
+
+      return {
+        instances: Object.values(project.instances),
+        hubs: Object.values(project.hubs),
+      }
+    } catch (error) {
+      throw new Error("Failed to get project instances", { cause: error })
+    }
+  }
+
+  async createProject(projectId: string): Promise<void> {
+    try {
+      await this.withProject(projectId, () => {
+        // Create an empty project
+        return { instances: {}, hubs: {} }
+      })
+    } catch (error) {
+      throw new Error("Failed to create project", { cause: error })
+    }
+  }
+
+  async createInstance(projectId: string, instance: InstanceModel): Promise<InstanceModel> {
+    try {
+      return await this.withProject(projectId, project => {
+        if (project.instances[instance.id]) {
+          throw new Error(`Instance ${instance.id} already exists`)
+        }
+
+        project.instances[instance.id] = instance
+        return instance
+      })
+    } catch (error) {
+      throw new Error("Failed to create project instance", { cause: error })
+    }
+  }
+
+  async updateInstance(
+    projectId: string,
+    instanceId: string,
+    patch: InstanceModelPatch,
+  ): Promise<InstanceModel> {
+    try {
+      return await this.withInstance(projectId, instanceId, instance => {
+        if (patch.args) {
+          instance.args = patch.args
+        }
+
+        if (patch.position) {
+          instance.position = patch.position
+        }
+
+        if (patch.inputs) {
+          if (Object.keys(patch.inputs).length > 0) {
+            instance.inputs = patch.inputs
+          } else {
+            delete instance.inputs
+          }
+        }
+
+        if (patch.hubInputs) {
+          if (Object.keys(patch.hubInputs).length > 0) {
+            instance.hubInputs = patch.hubInputs
+          } else {
+            delete instance.hubInputs
+          }
+        }
+
+        if (patch.injectionInputs) {
+          if (patch.injectionInputs.length > 0) {
+            instance.injectionInputs = patch.injectionInputs
+          } else {
+            delete instance.injectionInputs
+          }
+        }
+
+        return instance
+      })
+    } catch (error) {
+      throw new Error("Failed to update project instance", { cause: error })
+    }
+  }
+
+  async deleteInstance(projectId: string, instanceId: string): Promise<void> {
+    try {
+      await this.withProject(projectId, project => {
+        if (!project.instances[instanceId]) {
+          throw new Error(`Instance ${instanceId} not found`)
+        }
+
+        delete project.instances[instanceId]
+
+        // Delete all inputs of instances that reference deleted instance
+        for (const otherInstance of Object.values(project.instances)) {
+          if (!otherInstance.inputs) {
+            continue
+          }
+
+          this.deleteInstanceReferences(otherInstance.inputs, instanceId)
+
+          if (Object.keys(otherInstance.inputs).length === 0) {
+            delete otherInstance.inputs
+          }
+        }
+
+        // Delete all inputs of hubs that reference deleted instance
+        for (const hub of Object.values(project.hubs)) {
+          if (!hub.inputs) {
+            continue
+          }
+
+          hub.inputs = hub.inputs.filter(input => input.instanceId !== instanceId)
+
+          if (hub.inputs.length === 0) {
+            delete hub.inputs
+          }
+        }
+      })
+    } catch (error) {
+      throw new Error("Failed to delete project instance", { cause: error })
+    }
+  }
+
+  private deleteInstanceReferences(
+    inputs: Record<string, InstanceInput[]>,
+    instanceId: string,
+  ): void {
+    for (const [inputKey, input] of Object.entries(inputs)) {
+      inputs[inputKey] = input.filter(inputItem => inputItem.instanceId !== instanceId)
+
+      if (inputs[inputKey].length === 0) {
+        delete inputs[inputKey]
+      }
+    }
+  }
+
+  async renameInstance(
+    projectId: string,
+    instanceId: string,
+    newName: string,
+  ): Promise<InstanceModel> {
+    try {
+      return await this.withProject(projectId, project => {
+        // Rename the instance
+        const instance = project.instances[instanceId]
+        if (!instance) {
+          throw new Error(`Instance ${instanceId} not found`)
+        }
+
+        const newInstanceId = getInstanceId(instance.type, newName)
+        if (project.instances[newInstanceId]) {
+          throw new Error(`Instance ${newInstanceId} already exists`)
+        }
+
+        delete project.instances[instanceId]
+        instance.id = newInstanceId
+        instance.name = newName
+        project.instances[newInstanceId] = instance
+
+        // Update all references to the instance from other instances
+        for (const otherInstance of Object.values(project.instances)) {
+          for (const inputs of Object.values(otherInstance.inputs ?? {})) {
+            this.renameInstanceReferences(inputs, instanceId, instance.id)
+          }
+        }
+
+        // Update all references to the instance from hubs
+        for (const hub of Object.values(project.hubs)) {
+          this.renameInstanceReferences(hub.inputs ?? [], instanceId, instance.id)
+        }
+
+        return instance
+      })
+    } catch (error) {
+      throw new Error("Failed to rename project instance", { cause: error })
+    }
+  }
+
+  private renameInstanceReferences(
+    inputs: InstanceInput[],
+    instanceId: string,
+    newInstanceId: string,
+  ): void {
+    for (const input of inputs) {
+      if (input.instanceId === instanceId) {
+        input.instanceId = newInstanceId
+      }
+    }
+  }
+
+  async createHub(projectId: string, hub: HubModel): Promise<HubModel> {
+    try {
+      return await this.withProject(projectId, project => {
+        if (project.hubs[hub.id]) {
+          throw new Error(`Hub ${hub.id} already exists`)
+        }
+
+        project.hubs[hub.id] = hub
+        return hub
+      })
+    } catch (error) {
+      throw new Error("Failed to create project hub", { cause: error })
+    }
+  }
+
+  async updateHub(projectId: string, hubId: string, patch: HubModelPatch): Promise<HubModel> {
+    try {
+      return await this.withProject(projectId, project => {
+        const hub = project.hubs[hubId]
+        if (!hub) {
+          throw new Error(`Hub ${hubId} not found`)
+        }
+
+        if (patch.position) {
+          hub.position = patch.position
+        }
+
+        if (patch.inputs) {
+          if (patch.inputs.length > 0) {
+            hub.inputs = patch.inputs
+          } else {
+            delete hub.inputs
+          }
+        }
+
+        if (patch.injectionInputs) {
+          if (patch.injectionInputs.length > 0) {
+            hub.injectionInputs = patch.injectionInputs
+          } else {
+            delete hub.injectionInputs
+          }
+        }
+
+        return hub
+      })
+    } catch (error) {
+      throw new Error("Failed to update project hub", { cause: error })
+    }
+  }
+
+  async deleteHub(projectId: string, hubId: string): Promise<void> {
+    try {
+      await this.withProject(projectId, project => {
+        if (!project.hubs[hubId]) {
+          throw new Error(`Hub ${hubId} not found`)
+        }
+
+        delete project.hubs[hubId]
+
+        // Delete all inputs of instances that reference deleted hub
+        for (const instance of Object.values(project.instances)) {
+          if (instance.hubInputs) {
+            this.deleteHubReferences(instance.hubInputs, hubId)
+
+            if (Object.keys(instance.hubInputs).length === 0) {
+              delete instance.hubInputs
+            }
+          }
+
+          if (instance.injectionInputs) {
+            instance.injectionInputs = instance.injectionInputs.filter(
+              input => input.hubId !== hubId,
+            )
+
+            if (instance.injectionInputs.length === 0) {
+              delete instance.injectionInputs
+            }
+          }
+        }
+
+        // Delete all inputs of hubs that reference deleted hub
+        for (const otherHub of Object.values(project.hubs)) {
+          if (!otherHub.injectionInputs) {
+            continue
+          }
+
+          otherHub.injectionInputs = otherHub.injectionInputs.filter(input => input.hubId !== hubId)
+
+          if (otherHub.injectionInputs.length === 0) {
+            delete otherHub.injectionInputs
+          }
+        }
+      })
+    } catch (error) {
+      throw new Error("Failed to delete project hub", { cause: error })
+    }
+  }
+
+  private deleteHubReferences(inputs: Record<string, HubInput[]>, hubId: string): void {
+    for (const [inputKey, input] of Object.entries(inputs)) {
+      inputs[inputKey] = input.filter(inputItem => inputItem.hubId !== hubId)
+
+      if (inputs[inputKey].length === 0) {
+        delete inputs[inputKey]
+      }
+    }
+  }
+
+  private getProjectPath(projectId: string) {
+    return `${this.projectsDir}/${projectId}.json`
+  }
+
+  private async loadProject(projectId: string) {
+    const projectPath = this.getProjectPath(projectId)
+
+    try {
+      const content = await readFile(projectPath, "utf-8")
+
+      return projectModelSchema.parse(JSON.parse(content))
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+        return { instances: {}, hubs: {} }
+      }
+
+      throw error
+    }
+  }
+
+  private async writeProject(projectId: string, project: z.infer<typeof projectModelSchema>) {
+    const projectPath = this.getProjectPath(projectId)
+    const content = JSON.stringify(project, undefined, 2)
+
+    await writeFile(projectPath, content)
+  }
+
+  private async withInstance<T>(
+    projectId: string,
+    instanceId: string,
+    callback: (instance: InstanceModel) => T,
+  ): Promise<T> {
+    return await this.withProject(projectId, project => {
+      const instance = project.instances[instanceId]
+      if (!instance) {
+        throw new Error(`Instance ${instanceId} not found`)
+      }
+
+      return callback(instance)
+    })
+  }
+
+  private async withProject<T>(
+    projectId: string,
+    callback: (project: z.infer<typeof projectModelSchema>) => T,
+  ): Promise<T> {
+    const project = await this.loadProject(projectId)
+
+    const result = callback(project)
+    await this.writeProject(projectId, project)
+
+    return result
+  }
+
+  public static async create(config: z.infer<typeof localProjectBackendConfig>) {
+    let projectsPath = config.HIGHSTATE_BACKEND_PROJECT_PROJECTS_DIR
+    if (!projectsPath) {
+      const [mainProjectPath] = await resolveMainLocalProject()
+      projectsPath = resolve(mainProjectPath, "projects")
+    }
+
+    await mkdir(projectsPath, { recursive: true })
+
+    return new LocalProjectBackend(projectsPath)
+  }
+}

package/src/project/lock.ts

@@ -0,0 +1,39 @@
+import type { BetterLock as BetterLockType } from "better-lock/dist/better_lock"
+import { BetterLock } from "better-lock"
+
+export class ProjectLock {
+  constructor(private readonly lock: BetterLockType, private readonly projectId: string) {}
+
+  canImmediatelyAcquireLock(instanceId: string): boolean {
+    return this.lock.canAcquire(`${this.projectId}/${instanceId}`)
+  }
+
+  canImmediatelyAcquireLocks(instanceIds: string[]): boolean {
+    for (const instanceId of instanceIds) {
+      if (!this.canImmediatelyAcquireLock(instanceId)) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  lockInstance<T>(instanceId: string, fn: () => Promise<T>): Promise<T> {
+    return this.lock.acquire(`${this.projectId}/${instanceId}`, fn)
+  }
+
+  lockInstances<T>(instanceIds: string[], fn: () => Promise<T>): Promise<T> {
+    return this.lock.acquire(
+      instanceIds.map(id => `${this.projectId}/${id}`),
+      fn,
+    )
+  }
+}
+
+export class ProjectLockManager {
+  private readonly lock = new BetterLock()
+
+  getLock(projectId: string) {
+    return new ProjectLock(this.lock, projectId)
+  }
+}