@tanstack/electron-db-sqlite-persistence 0.1.2

package/src/errors.ts

@@ -0,0 +1,110 @@
+import type {
+  ElectronPersistenceMethod,
+  ElectronSerializedError,
+} from './protocol'
+
+type ElectronPersistenceErrorOptions = {
+  code?: string
+  cause?: unknown
+}
+
+export class ElectronPersistenceError extends Error {
+  readonly code: string | undefined
+
+  constructor(message: string, options?: ElectronPersistenceErrorOptions) {
+    super(message, { cause: options?.cause })
+    this.name = `ElectronPersistenceError`
+    this.code = options?.code
+  }
+}
+
+export class UnknownElectronPersistenceCollectionError extends ElectronPersistenceError {
+  readonly collectionId: string
+
+  constructor(collectionId: string) {
+    super(
+      `Unknown electron persistence collection "${collectionId}". Register the collection adapter in the main process host.`,
+      {
+        code: `UNKNOWN_COLLECTION`,
+      },
+    )
+    this.name = `UnknownElectronPersistenceCollectionError`
+    this.collectionId = collectionId
+  }
+}
+
+export class UnsupportedElectronPersistenceMethodError extends ElectronPersistenceError {
+  readonly method: ElectronPersistenceMethod
+  readonly collectionId: string
+
+  constructor(method: ElectronPersistenceMethod, collectionId: string) {
+    super(
+      `Method "${method}" is not supported by the electron persistence adapter for collection "${collectionId}".`,
+      {
+        code: `UNSUPPORTED_METHOD`,
+      },
+    )
+    this.name = `UnsupportedElectronPersistenceMethodError`
+    this.method = method
+    this.collectionId = collectionId
+  }
+}
+
+export class ElectronPersistenceProtocolError extends ElectronPersistenceError {
+  constructor(message: string, options?: ElectronPersistenceErrorOptions) {
+    super(message, {
+      code: options?.code ?? `INVALID_PROTOCOL`,
+      cause: options?.cause,
+    })
+    this.name = `ElectronPersistenceProtocolError`
+  }
+}
+
+export class ElectronPersistenceTimeoutError extends ElectronPersistenceError {
+  constructor(message: string) {
+    super(message, {
+      code: `TIMEOUT`,
+    })
+    this.name = `ElectronPersistenceTimeoutError`
+  }
+}
+
+export class ElectronPersistenceRpcError extends ElectronPersistenceError {
+  readonly method: ElectronPersistenceMethod
+  readonly collectionId: string
+  readonly requestId: string
+  readonly remoteName: string
+
+  constructor(
+    method: ElectronPersistenceMethod,
+    collectionId: string,
+    requestId: string,
+    serializedError: ElectronSerializedError,
+  ) {
+    super(
+      `${serializedError.name}: ${serializedError.message} (method=${method}, collection=${collectionId}, request=${requestId})`,
+      {
+        code: serializedError.code ?? `REMOTE_ERROR`,
+      },
+    )
+    this.name = `ElectronPersistenceRpcError`
+    this.method = method
+    this.collectionId = collectionId
+    this.requestId = requestId
+    this.remoteName = serializedError.name
+  }
+
+  static fromSerialized(
+    method: ElectronPersistenceMethod,
+    collectionId: string,
+    requestId: string,
+    serializedError: ElectronSerializedError,
+  ): ElectronPersistenceRpcError {
+    return new ElectronPersistenceRpcError(
+      method,
+      collectionId,
+      requestId,
+      serializedError,
+    )
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { exposeElectronSQLitePersistence } from './main'
+export type {
+  ElectronIpcMainLike,
+  ElectronSQLiteMainProcessOptions,
+} from './main'
+export { createElectronSQLitePersistence } from './renderer'
+export type {
+  ElectronIpcRendererLike,
+  ElectronSQLitePersistenceOptions,
+} from './renderer'
+export { ElectronCollectionCoordinator } from './electron-coordinator'
+export type { ElectronCollectionCoordinatorOptions } from './electron-coordinator'
+export { persistedCollectionOptions } from '@tanstack/db-sqlite-persistence-core'
+export type {
+  PersistedCollectionCoordinator,
+  PersistedCollectionPersistence,
+} from '@tanstack/db-sqlite-persistence-core'

package/src/main.ts

@@ -0,0 +1,315 @@
+import { InvalidPersistedCollectionConfigError } from '@tanstack/db-sqlite-persistence-core'
+import {
+  DEFAULT_ELECTRON_PERSISTENCE_CHANNEL,
+  ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+} from './protocol'
+import type {
+  PersistedCollectionPersistence,
+  PersistenceAdapter,
+  SQLitePullSinceResult,
+} from '@tanstack/db-sqlite-persistence-core'
+import type {
+  ElectronPersistedKey,
+  ElectronPersistedRow,
+  ElectronPersistenceRequestEnvelope,
+  ElectronPersistenceResponseEnvelope,
+  ElectronSerializedError,
+} from './protocol'
+
+type ElectronMainPersistenceAdapter = PersistenceAdapter<
+  ElectronPersistedRow,
+  ElectronPersistedKey
+> & {
+  loadCollectionMetadata?: (
+    collectionId: string,
+  ) => Promise<Array<{ key: string; value: unknown }>>
+  scanRows?: (
+    collectionId: string,
+    options?: { metadataOnly?: boolean },
+  ) => Promise<
+    Array<{
+      key: ElectronPersistedKey
+      value: ElectronPersistedRow
+      metadata?: unknown
+    }>
+  >
+  pullSince?: (
+    collectionId: string,
+    fromRowVersion: number,
+  ) => Promise<SQLitePullSinceResult<ElectronPersistedKey>>
+  getStreamPosition?: (collectionId: string) => Promise<{
+    latestTerm: number
+    latestSeq: number
+    latestRowVersion: number
+  }>
+}
+
+function serializeError(error: unknown): ElectronSerializedError {
+  const fallbackMessage = `Unknown electron persistence error`
+
+  if (!(error instanceof Error)) {
+    return {
+      name: `Error`,
+      message: fallbackMessage,
+      code: undefined,
+    }
+  }
+
+  const codedError = error as Error & { code?: unknown }
+  return {
+    name: error.name || `Error`,
+    message: error.message || fallbackMessage,
+    stack: error.stack,
+    code: typeof codedError.code === `string` ? codedError.code : undefined,
+  }
+}
+
+function createErrorResponse(
+  request: ElectronPersistenceRequestEnvelope,
+  error: unknown,
+): ElectronPersistenceResponseEnvelope {
+  return {
+    v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+    requestId: request.requestId,
+    method: request.method,
+    ok: false,
+    error: serializeError(error),
+  }
+}
+
+function assertValidRequest(request: ElectronPersistenceRequestEnvelope): void {
+  if (request.v !== ELECTRON_PERSISTENCE_PROTOCOL_VERSION) {
+    throw new InvalidPersistedCollectionConfigError(
+      `Unsupported electron persistence protocol version "${request.v}"`,
+    )
+  }
+
+  if (
+    typeof request.requestId !== `string` ||
+    request.requestId.trim().length === 0
+  ) {
+    throw new InvalidPersistedCollectionConfigError(
+      `Electron persistence requestId cannot be empty`,
+    )
+  }
+
+  if (
+    typeof request.collectionId !== `string` ||
+    request.collectionId.trim().length === 0
+  ) {
+    throw new InvalidPersistedCollectionConfigError(
+      `Electron persistence collectionId cannot be empty`,
+    )
+  }
+}
+
+async function executeRequestAgainstAdapter(
+  request: ElectronPersistenceRequestEnvelope,
+  adapter: ElectronMainPersistenceAdapter,
+): Promise<ElectronPersistenceResponseEnvelope> {
+  switch (request.method) {
+    case `loadSubset`: {
+      const result = await adapter.loadSubset(
+        request.collectionId,
+        request.payload.options,
+        request.payload.ctx,
+      )
+      return {
+        v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+        requestId: request.requestId,
+        method: request.method,
+        ok: true,
+        result,
+      }
+    }
+
+    case `loadCollectionMetadata`: {
+      if (!adapter.loadCollectionMetadata) {
+        throw new InvalidPersistedCollectionConfigError(
+          `loadCollectionMetadata is not supported by the configured electron persistence adapter`,
+        )
+      }
+      const result = await adapter.loadCollectionMetadata(request.collectionId)
+      return {
+        v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+        requestId: request.requestId,
+        method: request.method,
+        ok: true,
+        result,
+      }
+    }
+
+    case `scanRows`: {
+      if (!adapter.scanRows) {
+        throw new InvalidPersistedCollectionConfigError(
+          `scanRows is not supported by the configured electron persistence adapter`,
+        )
+      }
+      const result = await adapter.scanRows(
+        request.collectionId,
+        request.payload.options,
+      )
+      return {
+        v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+        requestId: request.requestId,
+        method: request.method,
+        ok: true,
+        result,
+      }
+    }
+
+    case `applyCommittedTx`: {
+      await adapter.applyCommittedTx(request.collectionId, request.payload.tx)
+      return {
+        v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+        requestId: request.requestId,
+        method: request.method,
+        ok: true,
+        result: null,
+      }
+    }
+
+    case `ensureIndex`: {
+      await adapter.ensureIndex(
+        request.collectionId,
+        request.payload.signature,
+        request.payload.spec,
+      )
+      return {
+        v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+        requestId: request.requestId,
+        method: request.method,
+        ok: true,
+        result: null,
+      }
+    }
+
+    case `markIndexRemoved`: {
+      if (!adapter.markIndexRemoved) {
+        throw new InvalidPersistedCollectionConfigError(
+          `markIndexRemoved is not supported by the configured electron persistence adapter`,
+        )
+      }
+      await adapter.markIndexRemoved(
+        request.collectionId,
+        request.payload.signature,
+      )
+      return {
+        v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+        requestId: request.requestId,
+        method: request.method,
+        ok: true,
+        result: null,
+      }
+    }
+
+    case `pullSince`: {
+      if (!adapter.pullSince) {
+        throw new InvalidPersistedCollectionConfigError(
+          `pullSince is not supported by the configured electron persistence adapter`,
+        )
+      }
+      const result = await adapter.pullSince(
+        request.collectionId,
+        request.payload.fromRowVersion,
+      )
+      return {
+        v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+        requestId: request.requestId,
+        method: request.method,
+        ok: true,
+        result,
+      }
+    }
+
+    case `getStreamPosition`: {
+      if (!adapter.getStreamPosition) {
+        throw new InvalidPersistedCollectionConfigError(
+          `getStreamPosition is not supported by the configured electron persistence adapter`,
+        )
+      }
+      const position = await adapter.getStreamPosition(request.collectionId)
+      return {
+        v: ELECTRON_PERSISTENCE_PROTOCOL_VERSION,
+        requestId: request.requestId,
+        method: request.method,
+        ok: true,
+        result: position,
+      }
+    }
+  }
+}
+
+function resolveModeAwarePersistence(
+  persistence: PersistedCollectionPersistence<
+    ElectronPersistedRow,
+    ElectronPersistedKey
+  >,
+  request: ElectronPersistenceRequestEnvelope,
+): PersistedCollectionPersistence<ElectronPersistedRow, ElectronPersistedKey> {
+  const mode = request.resolution?.mode ?? `sync-absent`
+  const schemaVersion = request.resolution?.schemaVersion
+  const collectionAwarePersistence =
+    persistence.resolvePersistenceForCollection?.({
+      collectionId: request.collectionId,
+      mode,
+      schemaVersion,
+    })
+  if (collectionAwarePersistence) {
+    return collectionAwarePersistence
+  }
+
+  const modeAwarePersistence = persistence.resolvePersistenceForMode?.(mode)
+  return modeAwarePersistence ?? persistence
+}
+
+export type ElectronIpcMainLike = {
+  handle: (
+    channel: string,
+    listener: (
+      event: unknown,
+      request: ElectronPersistenceRequestEnvelope,
+    ) => Promise<ElectronPersistenceResponseEnvelope>,
+  ) => void
+  removeHandler?: (channel: string) => void
+}
+
+export type ElectronSQLiteMainProcessOptions = {
+  persistence: PersistedCollectionPersistence<
+    ElectronPersistedRow,
+    ElectronPersistedKey
+  >
+  ipcMain: ElectronIpcMainLike
+  channel?: string
+}
+
+export function exposeElectronSQLitePersistence(
+  options: ElectronSQLiteMainProcessOptions,
+): () => void {
+  const channel = options.channel ?? DEFAULT_ELECTRON_PERSISTENCE_CHANNEL
+  options.ipcMain.handle(
+    channel,
+    async (
+      _event,
+      request: ElectronPersistenceRequestEnvelope,
+    ): Promise<ElectronPersistenceResponseEnvelope> => {
+      try {
+        assertValidRequest(request)
+        const modeAwarePersistence = resolveModeAwarePersistence(
+          options.persistence,
+          request,
+        )
+        return await executeRequestAgainstAdapter(
+          request,
+          modeAwarePersistence.adapter,
+        )
+      } catch (error) {
+        return createErrorResponse(request, error)
+      }
+    },
+  )
+
+  return () => {
+    options.ipcMain.removeHandler?.(channel)
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,137 @@
+import type { LoadSubsetOptions } from '@tanstack/db'
+import type {
+  PersistedCollectionMode,
+  PersistedIndexSpec,
+  PersistedTx,
+  SQLitePullSinceResult,
+} from '@tanstack/db-sqlite-persistence-core'
+
+export const ELECTRON_PERSISTENCE_PROTOCOL_VERSION = 1 as const
+export const DEFAULT_ELECTRON_PERSISTENCE_CHANNEL = `tanstack-db:sqlite-persistence`
+
+export type ElectronPersistedRow = Record<string, unknown>
+export type ElectronPersistedKey = string | number
+
+export type ElectronPersistenceResolution = {
+  mode: PersistedCollectionMode
+  schemaVersion?: number
+}
+
+export type ElectronPersistenceMethod =
+  | `loadSubset`
+  | `loadCollectionMetadata`
+  | `scanRows`
+  | `applyCommittedTx`
+  | `ensureIndex`
+  | `markIndexRemoved`
+  | `pullSince`
+  | `getStreamPosition`
+
+export type ElectronPersistencePayloadMap = {
+  loadSubset: {
+    options: LoadSubsetOptions
+    ctx?: { requiredIndexSignatures?: ReadonlyArray<string> }
+  }
+  loadCollectionMetadata: {}
+  scanRows: {
+    options?: {
+      metadataOnly?: boolean
+    }
+  }
+  applyCommittedTx: {
+    tx: PersistedTx<ElectronPersistedRow, ElectronPersistedKey>
+  }
+  ensureIndex: {
+    signature: string
+    spec: PersistedIndexSpec
+  }
+  markIndexRemoved: {
+    signature: string
+  }
+  pullSince: {
+    fromRowVersion: number
+  }
+  getStreamPosition: {}
+}
+
+export type ElectronPersistenceResultMap = {
+  loadSubset: Array<{ key: ElectronPersistedKey; value: ElectronPersistedRow }>
+  loadCollectionMetadata: Array<{ key: string; value: unknown }>
+  scanRows: Array<{
+    key: ElectronPersistedKey
+    value: ElectronPersistedRow
+    metadata?: unknown
+  }>
+  applyCommittedTx: null
+  ensureIndex: null
+  markIndexRemoved: null
+  pullSince: SQLitePullSinceResult<ElectronPersistedKey>
+  getStreamPosition: {
+    latestTerm: number
+    latestSeq: number
+    latestRowVersion: number
+  }
+}
+
+export type ElectronSerializedError = {
+  name: string
+  message: string
+  stack?: string
+  code?: string
+}
+
+export type ElectronPersistenceRequestByMethod = {
+  [Method in ElectronPersistenceMethod]: {
+    v: number
+    requestId: string
+    collectionId: string
+    resolution?: ElectronPersistenceResolution
+    method: Method
+    payload: ElectronPersistencePayloadMap[Method]
+  }
+}
+
+export type ElectronPersistenceRequest<
+  TMethod extends ElectronPersistenceMethod = ElectronPersistenceMethod,
+> = ElectronPersistenceRequestByMethod[TMethod]
+
+export type ElectronPersistenceRequestEnvelope =
+  ElectronPersistenceRequestByMethod[ElectronPersistenceMethod]
+
+type ElectronPersistenceSuccessResponseByMethod = {
+  [Method in ElectronPersistenceMethod]: {
+    v: number
+    requestId: string
+    method: Method
+    ok: true
+    result: ElectronPersistenceResultMap[Method]
+  }
+}
+
+type ElectronPersistenceErrorResponseByMethod = {
+  [Method in ElectronPersistenceMethod]: {
+    v: number
+    requestId: string
+    method: Method
+    ok: false
+    error: ElectronSerializedError
+  }
+}
+
+export type ElectronPersistenceResponse<
+  TMethod extends ElectronPersistenceMethod = ElectronPersistenceMethod,
+> =
+  | ElectronPersistenceSuccessResponseByMethod[TMethod]
+  | ElectronPersistenceErrorResponseByMethod[TMethod]
+
+export type ElectronPersistenceResponseEnvelope =
+  ElectronPersistenceResponse<ElectronPersistenceMethod>
+
+export type ElectronPersistenceRequestHandler = (
+  request: ElectronPersistenceRequestEnvelope,
+) => Promise<ElectronPersistenceResponseEnvelope>
+
+export type ElectronPersistenceInvoke = (
+  channel: string,
+  request: ElectronPersistenceRequestEnvelope,
+) => Promise<ElectronPersistenceResponseEnvelope>