@highstate/backend 0.9.14 → 0.9.16

package/src/state/factory.ts

@@ -1,22 +1,20 @@
 import type { StateBackend } from "./abstractions"
 import type { Logger } from "pino"
-import type { LocalPulumiHost } from "../common"
 import { z } from "zod"
 import { LocalStateBackend, localStateBackendConfig } from "./local"
 
 export const stateBackendConfig = z.object({
-  HIGHSTATE_BACKEND_STATE_TYPE: z.enum(["local"]).default("local"),
+  HIGHSTATE_STATE_BACKEND_TYPE: z.enum(["local"]).default("local"),
   ...localStateBackendConfig.shape,
 })
 
 export function createStateBackend(
   config: z.infer<typeof stateBackendConfig>,
-  localPulumiHost: LocalPulumiHost,
   logger: Logger,
 ): Promise<StateBackend> {
-  switch (config.HIGHSTATE_BACKEND_STATE_TYPE) {
+  switch (config.HIGHSTATE_STATE_BACKEND_TYPE) {
     case "local": {
-      return LocalStateBackend.create(config, localPulumiHost, logger)
+      return LocalStateBackend.create(config, logger)
     }
   }
 }

package/src/state/index.ts

@@ -1,3 +1,6 @@
 export * from "./abstractions"
 export * from "./factory"
 export * from "./manager"
+export * from "./repository"
+export * from "./keyring"
+export * from "./encryption"

package/src/state/keyring.ts

@@ -0,0 +1,22 @@
+import type { Logger } from "pino"
+import { AsyncEntry, findCredentialsAsync } from "@napi-rs/keyring"
+import { generateIdentity } from "age-encryption"
+
+const serviceName = "io.highstate.backend"
+const accountName = "identity"
+
+export async function getOrCreateBackendIdentity(logger: Logger): Promise<string> {
+  const credentials = await findCredentialsAsync(serviceName)
+  const entry = credentials.find(entry => entry.account === accountName)
+
+  if (entry) {
+    logger.debug("found existing backend identity in keyring")
+    return entry.password
+  }
+
+  const newIdentity = await generateIdentity()
+  await new AsyncEntry(serviceName, accountName).setPassword(newIdentity)
+
+  logger.info("created new backend identity and stored it in the OS keyring")
+  return newIdentity
+}

package/src/state/local/backend.ts

@@ -0,0 +1,299 @@
+import type { AbstractLevel } from "abstract-level"
+import type { Logger } from "pino"
+import { resolve } from "node:path"
+import { z } from "zod"
+import {
+  CollectionBackend,
+  type StateBackend,
+  type StateBatch,
+  type StateCollection,
+  type StateSnapshot,
+} from "../abstractions"
+import { LocalStateCollection } from "./collection"
+
+export const localStateBackendConfig = z.object({
+  HIGHSTATE_STATE_BACKEND_LOCAL_DIR: z.string().optional(),
+})
+
+/**
+ * A state backend that stores the state in a local LevelDB database.
+ *
+ * The default state location is `~/.highstate/state.db`.
+ *
+ * Storage Structure:
+ *
+ * ## System Collections
+ * - `backend/id` - static id for the backend
+ * - `backend/encryptedMasterKey` - encrypted master key for the backend
+ * - `backend/projects/{projectId}` - project metadata
+ * - `backend/projectMasterKeys/{projectId}` - encrypted master keys for data encryption/decryption
+ * - `backend/projectHashNamespaces/{projectId}` - UUID namespaces for ID hashing per project
+ * - `backend/projectUnlockSuites/{projectId}` - unlock suites for project unlocking
+ *
+ * ## Project Collections
+ * - `projects/{projectId}/instanceStates/{instanceId}` - instance states
+ * - `projects/{projectId}/instanceLocks/{instanceId}` - instance locks for operation coordination
+ * - `projects/{projectId}/terminalSessions/{sessionId}` - terminal sessions (sessionId is UUIDv7)
+ * - `projects/{projectId}/activeTerminalSessions` - index of active terminal sessions
+ * - `projects/{projectId}/instances/{instanceId}/terminalSessions/{sessionId}` - terminal session index per instance
+ * - `projects/{projectId}/terminals/{terminalId}` - project terminals
+ * - `projects/{projectId}/terminalSpecs/{terminalId}` - terminal spec data
+ * - `projects/{projectId}/pages/{pageId}` - project pages
+ * - `projects/{projectId}/pageContents/{pageId}` - page content data
+ * - `projects/{projectId}/artifacts/{artifactId}` - project artifacts
+ * - `projects/{projectId}/artifactHashIndex/{hash}` - artifact hash to ID mapping
+ * - `projects/{projectId}/triggers/{triggerId}` - instance triggers
+ * - `projects/{projectId}/operations/{operationId}` - project operations
+ * - `projects/{projectId}/activeOperations/{operationId}` - index of active operations
+ * - `projects/{projectId}/unlockMethods/{methodId}` - unlock methods for the project
+ * - `projects/{projectId}/compositeInstances/{instanceId}` - evaluated composite instances
+ * - `projects/{projectId}/secrets/{secretId}` - project secrets
+ * - `projects/{projectId}/secretContents/{secretId}` - secret content data
+ * - `projects/{projectId}/serviceAccounts/{serviceAccountId}` - project service accounts
+ * - `projects/{projectId}/apiKeys/{apiKeyId}` - project API keys
+ * - `projects/{projectId}/apiKeyTokenIndex/{tokenHash}` - maps API key token hashes to API key IDs
+ * - `projects/{projectId}/workers/{workerId}` - project workers
+ * - `projects/{projectId}/workerRegistrations/{registrationId}` - worker registrations
+ * - `projects/{projectId}/workers/{workerId}/registrations/{registrationId}` - index of registrations per worker
+ * - `projects/{projectId}/workers/{workerId}/logs/{logId}` - worker logs (logId is UUIDv7)
+ *
+ * ## Operation Collections
+ * - `projects/{projectId}/operations/{operationId}/logs/{logId}` - operation logs (logId is UUIDv7)
+ * - `projects/{projectId}/operations/{operationId}/instances/{instanceId}/logs/{logId}` - instance-specific log index
+ *
+ * ## Terminal Collections
+ * - `projects/{projectId}/terminalSessions/{sessionId}/lines/{lineId}` - terminal session history (lineId is UUIDv7)
+ *
+ * ## Collection Metadata
+ * Each collection sublevel contains a special `_count` key that tracks the total number of documents
+ * in that collection for efficient pagination and querying without full iteration.
+ */
+export class LocalStateBackend implements StateBackend {
+  constructor(private readonly db: AbstractLevel<string, unknown>) {}
+
+  async getEncryptedBackendMasterKey(): Promise<string | null> {
+    const encryptedMasterKey = await this.db.get("backend/encryptedMasterKey")
+
+    return encryptedMasterKey ?? null
+  }
+
+  async setEncryptedBackendMasterKey(encryptedMasterKey: string): Promise<void> {
+    await this.db.put("backend/encryptedMasterKey", encryptedMasterKey)
+  }
+
+  async getStaticBackendId(): Promise<string | null> {
+    const ns = await this.db.get("backend/id")
+
+    return ns ?? null
+  }
+
+  async setStaticBackendId(namespace: string): Promise<void> {
+    await this.db.put("backend/id", namespace)
+  }
+
+  createStateBatch(): StateBatch {
+    const batch = this.db.batch()
+
+    return {
+      [CollectionBackend]: batch,
+      [Symbol.asyncDispose]: () => batch.close(),
+      write: () => batch.write(),
+    }
+  }
+
+  createStateSnapshot(): StateSnapshot {
+    const snapshot = this.db.snapshot()
+
+    return {
+      [CollectionBackend]: snapshot,
+      [Symbol.asyncDispose]: () => snapshot.close(),
+    }
+  }
+
+  createProjectCollection(): StateCollection {
+    return LocalStateCollection.create(this.db, "backend/projects")
+  }
+
+  createProjectMasterKeyCollection(): StateCollection {
+    return LocalStateCollection.create(this.db, "backend/projectMasterKeys")
+  }
+
+  createProjectIdHashNamespaceCollection(): StateCollection {
+    return LocalStateCollection.create(this.db, "backend/projectHashNamespaces")
+  }
+
+  createProjectUnlockSuiteCollection(): StateCollection {
+    return LocalStateCollection.create(this.db, "backend/projectUnlockSuites")
+  }
+
+  createTerminalSessionCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/terminalSessions`)
+  }
+
+  createActiveTerminalSessionIndexCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/activeTerminalSessions`)
+  }
+
+  createInstanceTerminalSessionIndexCollection(
+    projectId: string,
+    instanceId: string,
+  ): StateCollection {
+    return LocalStateCollection.create(
+      this.db,
+      `projects/${projectId}/instances/${instanceId}/terminalSessions`,
+    )
+  }
+
+  createTerminalCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/terminals`)
+  }
+
+  createTerminalSpecCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/terminalSpecs`)
+  }
+
+  createServiceAccountCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/serviceAccounts`)
+  }
+
+  createApiKeyCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/apiKeys`)
+  }
+
+  createApiKeyTokenIndexCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/apiKeyTokenIndex`)
+  }
+
+  createWorkerCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/workers`)
+  }
+
+  createWorkerRegistrationCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/workerRegistrations`)
+  }
+
+  createWorkerRegistrationIndexCollection(projectId: string, workerId: string): StateCollection {
+    return LocalStateCollection.create(
+      this.db,
+      `projects/${projectId}/workers/${workerId}/registrations`,
+    )
+  }
+
+  createWorkerLogCollection(projectId: string, workerId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/workers/${workerId}/logs`)
+  }
+
+  createPageCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/pages`)
+  }
+
+  createPageContentCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/pageContents`)
+  }
+
+  createArtifactCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/artifacts`)
+  }
+
+  createArtifactHashIndexCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/artifactHashIndex`)
+  }
+
+  createTriggerCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/triggers`)
+  }
+
+  createUnlockMethodCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/unlockMethods`)
+  }
+
+  createOperationCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/operations`)
+  }
+
+  createActiveOperationIndexCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/activeOperations`)
+  }
+
+  createSecretCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/secrets`)
+  }
+
+  createSecretContentCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/secretContents`)
+  }
+
+  createSecretIndexCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/secretIndex`)
+  }
+
+  createOperationLogCollection(projectId: string, operationId: string): StateCollection {
+    return LocalStateCollection.create(
+      this.db,
+      `projects/${projectId}/operations/${operationId}/logs`,
+    )
+  }
+
+  createInstanceLogIndexCollection(
+    projectId: string,
+    operationId: string,
+    instanceId: string,
+  ): StateCollection {
+    return LocalStateCollection.create(
+      this.db,
+      `projects/${projectId}/operations/${operationId}/instances/${instanceId}/logs`,
+    )
+  }
+
+  createTerminalSessionLineCollection(projectId: string, sessionId: string): StateCollection {
+    return LocalStateCollection.create(
+      this.db,
+      `projects/${projectId}/terminalSessions/${sessionId}/lines`,
+    )
+  }
+
+  createCompositeInstanceCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/compositeInstances`)
+  }
+
+  createInstanceStateCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/instanceStates`)
+  }
+
+  createInstanceLockCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/instanceLocks`)
+  }
+
+  createUserLayoutCollection(): StateCollection {
+    return LocalStateCollection.create(this.db, "backend/userLayouts")
+  }
+
+  createProjectViewportCollection(projectId: string): StateCollection {
+    return LocalStateCollection.create(this.db, `projects/${projectId}/viewports`)
+  }
+
+  createInstanceViewportCollection(projectId: string, instanceId: string): StateCollection {
+    return LocalStateCollection.create(
+      this.db,
+      `projects/${projectId}/instances/${instanceId}/viewports`,
+    )
+  }
+
+  static async create(
+    config: z.infer<typeof localStateBackendConfig>,
+    logger: Logger,
+  ): Promise<StateBackend> {
+    const childLogger = logger.child({ backend: "StateBackend", service: "LocalStateBackend" })
+
+    let location = config.HIGHSTATE_STATE_BACKEND_LOCAL_DIR
+    if (!location) {
+      location = resolve(process.env.HOME!, ".highstate", "state.db")
+      childLogger.debug({ location }, "using default local state backend location")
+    }
+
+    const { ClassicLevel } = await import("classic-level")
+    const db = new ClassicLevel<string, string>(location)
+
+    return new LocalStateBackend(db as unknown as AbstractLevel<string, unknown>)
+  }
+}

package/src/state/local/collection.ts

@@ -0,0 +1,342 @@
+import type {
+  AbstractChainedBatch,
+  AbstractIteratorOptions,
+  AbstractLevel,
+  AbstractSnapshot,
+  AbstractSublevel,
+} from "abstract-level"
+import type { CollectionQueryResult } from "../../shared"
+import { BetterLock } from "better-lock"
+import {
+  type StateCollection,
+  type CollectionQuery,
+  type StateSnapshot,
+  type StateBatch,
+  CollectionBackend,
+} from "../abstractions"
+
+type Sublevel = AbstractSublevel<
+  AbstractLevel<string, unknown>,
+  string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>,
+  string,
+  Uint8Array<ArrayBufferLike>
+>
+
+type ChainedBatch = AbstractChainedBatch<AbstractLevel<string, unknown>, string, Uint8Array>
+
+function getSnapshot(snapshot: StateSnapshot | undefined) {
+  if (snapshot && CollectionBackend in snapshot) {
+    return snapshot[CollectionBackend] as AbstractSnapshot
+  }
+
+  return undefined
+}
+
+function getBatch(batch: StateBatch | undefined) {
+  if (batch && CollectionBackend in batch) {
+    return batch[CollectionBackend] as AbstractChainedBatch<
+      AbstractLevel<string, unknown>,
+      string,
+      Uint8Array
+    >
+  }
+
+  return undefined
+}
+
+function getOrCreateBatch(db: AbstractLevel<string, unknown>, batch?: StateBatch) {
+  const explicitBatch = getBatch(batch)
+  if (explicitBatch) {
+    return { chainedBatch: explicitBatch, explicit: true }
+  }
+
+  const chainedBatch = db.batch() as unknown as AbstractChainedBatch<
+    AbstractLevel<string, unknown>,
+    string,
+    Uint8Array
+  >
+
+  return { chainedBatch, explicit: false }
+}
+
+/**
+ * LocalStateCollection implements StateCollection using LevelDB sublevel for binary data storage.
+ * It operates on raw binary data without any knowledge of the data structure.
+ */
+export class LocalStateCollection implements StateCollection {
+  private static readonly countKey = "_count"
+
+  // the lock for operations that modify the collection by first reading the item
+  // used to update the count key atomically
+  private readonly readWriteLock = new BetterLock()
+
+  constructor(
+    private readonly db: AbstractLevel<string, unknown>,
+    private readonly sublevel: Sublevel,
+  ) {}
+
+  async get(key: string, snapshot?: StateSnapshot): Promise<Uint8Array | undefined> {
+    return await this.sublevel.get(key, { snapshot: getSnapshot(snapshot) })
+  }
+
+  async getMany(keys: string[], snapshot?: StateSnapshot): Promise<(Uint8Array | undefined)[]> {
+    return await this.sublevel.getMany(keys, { snapshot: getSnapshot(snapshot) })
+  }
+
+  async getAll(snapshot?: StateSnapshot): Promise<Array<[string, Uint8Array]>> {
+    const result: Array<[string, Uint8Array]> = []
+    for await (const [key, value] of this.sublevel.iterator({ snapshot: getSnapshot(snapshot) })) {
+      // skip count key
+      if (key === LocalStateCollection.countKey) continue
+
+      result.push([key, value])
+    }
+
+    return result
+  }
+
+  async put(key: string, value: Uint8Array, batch?: StateBatch): Promise<void> {
+    await this.readWriteLock.acquire(key, async () => {
+      // check if this is a new item
+      const existing = await this.sublevel.get(key)
+      const isNewItem = !existing
+
+      const { chainedBatch, explicit } = getOrCreateBatch(this.db, batch)
+
+      chainedBatch.put(key, value, { sublevel: this.sublevel })
+
+      // update count if this is a new item
+      if (isNewItem) {
+        await this.incrementCount(1, chainedBatch)
+      }
+
+      if (!explicit) {
+        // if we created a new batch, we need to commit it
+        await chainedBatch.write()
+      }
+    })
+  }
+
+  async putMany(entries: Array<[string, Uint8Array]>, batch?: StateBatch): Promise<void> {
+    const keys = entries.map(([key]) => key)
+
+    await this.readWriteLock.acquire(keys, async () => {
+      // check which items are new
+      let newItemsCount = 0
+
+      for (const [key] of entries) {
+        const existing = await this.sublevel.get(key)
+        if (!existing) {
+          newItemsCount++
+        }
+      }
+
+      const { chainedBatch, explicit } = getOrCreateBatch(this.db, batch)
+
+      for (const [key, value] of entries) {
+        chainedBatch.put(key, value, { sublevel: this.sublevel })
+      }
+
+      // update count for new items
+      if (newItemsCount > 0) {
+        await this.incrementCount(newItemsCount, chainedBatch)
+      }
+
+      if (!explicit) {
+        // if we created a new batch, we need to commit it
+        await chainedBatch.write()
+      }
+    })
+  }
+
+  async delete(key: string, batch?: StateBatch): Promise<void> {
+    await this.readWriteLock.acquire(key, async () => {
+      // check if item exists before deleting
+      const existing = await this.sublevel.get(key)
+
+      const { chainedBatch, explicit } = getOrCreateBatch(this.db, batch)
+
+      chainedBatch.del(key, { sublevel: this.sublevel })
+
+      // update count if item existed
+      if (existing) {
+        await this.incrementCount(-1, chainedBatch)
+      }
+
+      if (!explicit) {
+        // if we created a new batch, we need to commit it
+        await chainedBatch.write()
+      }
+    })
+  }
+
+  async deleteMany(keys: string[], batch?: StateBatch): Promise<void> {
+    await this.readWriteLock.acquire(keys, async () => {
+      // check which items exist before deleting
+      const existingValues = await this.sublevel.getMany(keys)
+      let deletedItemsCount = 0
+
+      for (const value of existingValues) {
+        if (value) {
+          deletedItemsCount++
+        }
+      }
+
+      const { chainedBatch, explicit } = getOrCreateBatch(this.db, batch)
+
+      for (const id of keys) {
+        chainedBatch.del(id, { sublevel: this.sublevel })
+      }
+
+      // update count for deleted items
+      if (deletedItemsCount > 0) {
+        await this.incrementCount(-deletedItemsCount, chainedBatch)
+      }
+
+      if (!explicit) {
+        // if we created a new batch, we need to commit it
+        await chainedBatch.write()
+      }
+    })
+  }
+
+  async query(
+    query: CollectionQuery,
+    snapshot?: StateSnapshot,
+  ): Promise<CollectionQueryResult<[string, Uint8Array]>> {
+    const { cursor, count = 20, sort = "asc" } = query
+    const limit = Math.min(count, 100) // cap at 100
+
+    const items: [string, Uint8Array][] = []
+    let nextCursor: string | undefined
+
+    const iteratorOptions: AbstractIteratorOptions<string, Uint8Array> = {
+      limit: limit + 1, // +1 to account "_count" key
+      reverse: sort === "desc",
+      snapshot: getSnapshot(snapshot),
+    }
+
+    if (cursor && sort === "asc") {
+      iteratorOptions.gt = cursor // start after the cursor
+    } else if (cursor && sort === "desc") {
+      iteratorOptions.lt = cursor // start before the cursor
+    }
+
+    for await (const [key, value] of this.sublevel.iterator(iteratorOptions)) {
+      // skip count key
+      if (key === LocalStateCollection.countKey) continue
+
+      items.push([key, value])
+
+      // if we've collected enough documents, the last key becomes the next cursor
+      if (items.length === limit) {
+        nextCursor = key
+        break
+      }
+    }
+
+    // get total count for the collection
+    const total = await this.getTotalCount(snapshot)
+
+    return {
+      items,
+      total,
+      nextCursor,
+    }
+  }
+
+  async getTotalCount(snapshot?: StateSnapshot): Promise<number> {
+    const countData = await this.sublevel.get(LocalStateCollection.countKey, {
+      snapshot: getSnapshot(snapshot),
+    })
+
+    if (!countData) {
+      // if count doesn't exist, recalculate it
+      return await this.readWriteLock.acquire(LocalStateCollection.countKey, async () => {
+        return await this.recalculateCount()
+      })
+    }
+
+    // decode the count data and return it as an integer
+    // if the data is not a valid number, recalculate it
+    const count = new TextDecoder().decode(countData)
+    const countValue = parseInt(count, 10)
+    if (isNaN(countValue)) {
+      return await this.readWriteLock.acquire(LocalStateCollection.countKey, async () => {
+        return await this.recalculateCount()
+      })
+    }
+
+    return countValue
+  }
+
+  /**
+   * Helper method to increment the count by a specific amount.
+   *
+   * MUST be used within a lock to ensure atomicity.
+   */
+  private async incrementCount(amount: number, batch: ChainedBatch): Promise<void> {
+    await this.readWriteLock.acquire(LocalStateCollection.countKey, async () => {
+      const currentCount = await this.sublevel.get(LocalStateCollection.countKey)
+      if (!currentCount) {
+        await this.recalculateCount()
+        return
+      }
+
+      const count = new TextDecoder().decode(currentCount)
+      const currentCountValue = parseInt(count, 10)
+      if (isNaN(currentCountValue)) {
+        await this.recalculateCount()
+        return
+      }
+
+      const newCount = currentCountValue + amount
+      const countData = new TextEncoder().encode(newCount.toString())
+
+      batch.put(LocalStateCollection.countKey, countData, { sublevel: this.sublevel })
+    })
+  }
+
+  /**
+   * Helper method to recalculate the count from scratch by iterating through all keys.
+   */
+  private async recalculateCount(): Promise<number> {
+    // calculate the count by iterating through all keys
+    let count = 0
+    for await (const key of this.sublevel.keys()) {
+      if (key !== LocalStateCollection.countKey) {
+        count++
+      }
+    }
+
+    // store the calculated count
+    const countData = new TextEncoder().encode(count.toString())
+    await this.sublevel.put(LocalStateCollection.countKey, countData)
+
+    return count
+  }
+
+  iterate(snapshot?: StateSnapshot): AsyncIterable<[string, Uint8Array]> {
+    const sublevel = this.sublevel
+    const snapshotOption = getSnapshot(snapshot)
+
+    return {
+      async *[Symbol.asyncIterator](): AsyncGenerator<[string, Uint8Array], void, unknown> {
+        for await (const [key, value] of sublevel.iterator({ snapshot: snapshotOption })) {
+          // skip count key
+          if (key === LocalStateCollection.countKey) continue
+          yield [key, value] as [string, Uint8Array]
+        }
+      },
+    }
+  }
+
+  /**
+   * Creates a LocalStateCollection for the specified path using binary encoding.
+   */
+  static create(db: AbstractLevel<string, unknown>, path: string): LocalStateCollection {
+    const sublevel = db.sublevel<string, Uint8Array>(path, { valueEncoding: "buffer" })
+
+    return new LocalStateCollection(db, sublevel as Sublevel)
+  }
+}

package/src/state/local/index.ts

@@ -0,0 +1,2 @@
+export { LocalStateCollection } from "./collection"
+export { LocalStateBackend, localStateBackendConfig } from "./backend"