@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/react/index.d.ts

@@ -1,18 +1,73 @@
-import { L as LiveQueryOptions, a as LiveQuery, b as LiveQueryState } from '../types-CL6piSnD.js';
-import { O as OperationRef } from '../operation-registry-9DcvxcE5.js';
-import { P as Params } from '../types-zhnRXrsb.js';
+import { L as LiveQueryOptions, a as LiveQuery, b as LiveQueryState } from '../types-BCejqzNA.js';
+import { O as OperationRef } from '../operation-registry-hlbhqu7q.js';
+import { P as Params } from '../query-types-DL3LtPvY.js';
 
+/**
+ * The one method these hooks need from a database, so both a local
+ * `Database` and a `RemoteDatabase` satisfy it.
+ *
+ * @public
+ */
 interface LiveDatabase {
+    /** Opens a live query for a registered read. */
     live(operation: string | OperationRef<never, never>, args?: never, options?: LiveQueryOptions): Promise<LiveQuery<unknown>>;
 }
+/**
+ * Settings for one call to `useLiveQuery`.
+ *
+ * @public
+ */
 interface UseLiveQueryOptions extends LiveQueryOptions {
+    /** Set false to hold the query closed, which suits a query that depends on data you do not have yet. */
     enabled?: boolean;
 }
+/**
+ * Subscribes a component to a registered read and re-renders it as the rows change.
+ *
+ * The query closes when the component unmounts.
+ *
+ * @param database - Database the read runs against.
+ * @param operation - Name of the registered read.
+ * @param args - Arguments the read takes.
+ * @param options - Whether the query runs, plus the live-query settings.
+ * @returns Whether the query is pending, ready with rows, or failed.
+ *
+ * @public
+ */
 declare function useLiveQuery<Row = Record<string, unknown>>(database: LiveDatabase, operation: string, args?: Params, options?: UseLiveQueryOptions): LiveQueryState<Row>;
+/**
+ * Subscribes a component to a registered read and re-renders it as the rows change.
+ *
+ * @param database - Database the read runs against.
+ * @param operation - Reference to the registered read, which carries its argument and row types.
+ * @param args - Arguments the read takes.
+ * @param options - Whether the query runs, plus the live-query settings.
+ * @returns Whether the query is pending, ready with rows, or failed.
+ *
+ * @public
+ */
 declare function useLiveQuery<Args, Row>(database: LiveDatabase, operation: OperationRef<Args, Row>, args: Args, options?: UseLiveQueryOptions): LiveQueryState<Row>;
+/**
+ * Returns a stable callback that runs a registered write.
+ *
+ * @param database - Database the write runs against.
+ * @param command - Reference to the registered write, which carries its argument type.
+ * @returns A callback that takes the write's arguments and resolves with its result.
+ *
+ * @public
+ */
 declare function useCommand<Args, Result>(database: {
     execute(operation: OperationRef<Args, unknown>, args: Args): Promise<Result>;
 }, command: OperationRef<Args, unknown>): (args: Args) => Promise<Result>;
+/**
+ * Returns a stable callback that runs a statement or a registered write by name.
+ *
+ * @param database - Database the write runs against.
+ * @param command - The statement to run, or the name of a registered write.
+ * @returns A callback that takes the parameters and resolves with the result.
+ *
+ * @public
+ */
 declare function useCommand<Result>(database: {
     execute(sql: string, params?: Params): Promise<Result>;
 }, command: string): (params?: Params) => Promise<Result>;

package/dist/replication/coordinator/etcd.d.ts

@@ -1,18 +1,57 @@
 import { IOptions } from 'etcd3';
-import { C as ClusterCoordinator, A as AcquireControllerLeaseInput, b as AcquireControllerLeaseResult, c as RegisterNodeSessionInput, d as CoordinatorNodeSession, S as SetReplicationGroupStateInput, R as ReplicationGroupState, e as ReplicationGroupWatcher, f as CoordinatorWatchDisposer, g as CompareAndAdvancePrimaryTermInput, h as CompareAndAdvancePrimaryTermResult, U as UpdateInSyncSetInput, i as AdmitNodeToInSyncSetInput, j as UpdateNodeMaintenanceInput, P as PromoteEligibleReplicaInput } from '../../types-BsVabqSI.js';
+import { C as ClusterCoordinator, A as AcquireControllerLeaseInput, a as AcquireControllerLeaseResult, R as RegisterNodeSessionInput, b as CoordinatorNodeSession, S as SetReplicationGroupStateInput, c as ReplicationGroupState, d as ReplicationGroupWatcher, e as CoordinatorWatchDisposer, f as CompareAndAdvancePrimaryTermInput, g as CompareAndAdvancePrimaryTermResult, U as UpdateInSyncSetInput, h as AdmitNodeToInSyncSetInput, i as UpdateNodeMaintenanceInput, P as PromoteEligibleReplicaInput } from '../../types-CMBcFPhb.js';
 
+/**
+ * @public
+ *
+ * Where the etcd coordinator connects, under which key prefix it stores group state, and how it authenticates.
+ */
 interface EtcdClusterCoordinatorOptions {
+    /**
+     * etcd endpoints to connect to. Production access requires https addresses.
+     */
     hosts: string | string[];
+    /**
+     * Prefix applied to every key this coordinator writes, which keeps clusters apart in one etcd.
+     */
     keyPrefix: string;
+    /**
+     * TLS material, which production access requires.
+     */
     credentials?: IOptions['credentials'];
+    /**
+     * Username and password, as an alternative to a client certificate.
+     */
     auth?: IOptions['auth'];
+    /**
+     * Options passed straight through to the underlying gRPC channel.
+     */
     grpcOptions?: IOptions['grpcOptions'];
+    /**
+     * Milliseconds to wait for a connection to etcd.
+     */
     dialTimeoutMs?: number;
+    /**
+     * Milliseconds any single etcd call may take.
+     */
     defaultCallTimeoutMs?: number;
+    /**
+     * Accepts plain http endpoints without credentials, which suits tests only.
+     */
     allowInsecure?: boolean;
+    /**
+     * Called when a group watch fails so that a caller can log it or raise an alert.
+     */
     onWatcherError?: (error: Error) => void;
 }
 
+/**
+ * @public
+ *
+ * Stores primary authority, node sessions, group state, and the in-sync set in etcd.
+ *
+ * Build one with {@link createEtcdCoordinator}.
+ */
 declare class EtcdClusterCoordinator implements ClusterCoordinator {
     private readonly client;
     private readonly namespace;
@@ -22,25 +61,46 @@ declare class EtcdClusterCoordinator implements ClusterCoordinator {
     private readonly watchers;
     private readonly groups;
     constructor(options: EtcdClusterCoordinatorOptions);
+    /** Bids for the controller lease, and reports who holds it. */
     tryAcquireControllerLease(input: AcquireControllerLeaseInput): Promise<AcquireControllerLeaseResult>;
+    /** Extends a lease, and reports false once it has already lapsed. */
     renewLease(leaseId: string, ttlMs: number): Promise<boolean>;
+    /** Gives up a lease at once instead of waiting for it to lapse. */
     releaseLease(leaseId: string): Promise<boolean>;
+    /** Records one node as a live member of the cluster. */
     registerNodeSession(input: RegisterNodeSessionInput): Promise<CoordinatorNodeSession>;
+    /** Reads one node's session, and returns null once its lease has lapsed. */
     getLiveNodeSession(clusterId: string, nodeId: string): Promise<CoordinatorNodeSession | null>;
+    /** Ends one node's membership at once. */
     deregisterNodeSession(clusterId: string, nodeId: string): Promise<void>;
+    /** Writes the group's state, which seeds a new group or replaces an existing one. */
     setReplicationGroupState(input: SetReplicationGroupStateInput): Promise<ReplicationGroupState>;
+    /** Reads the group's state, and returns null when the group is absent. */
     getReplicationGroupState(clusterId: string, groupId: string): Promise<ReplicationGroupState | null>;
+    /** Calls back on each change to the group's state, and returns a function that stops the watch. */
     watchReplicationGroup(clusterId: string, groupId: string, watcher: ReplicationGroupWatcher): Promise<CoordinatorWatchDisposer>;
+    /** Promotes a node only while the group is still at the term the caller read. */
     compareAndAdvancePrimaryTerm(input: CompareAndAdvancePrimaryTermInput): Promise<CompareAndAdvancePrimaryTermResult>;
+    /** Replaces the group's in-sync set, and optionally moves its durability point. */
     updateInSyncSet(input: UpdateInSyncSetInput): Promise<ReplicationGroupState | null>;
+    /** Adds one caught-up node to the in-sync set. */
     admitNodeToInSyncSet(input: AdmitNodeToInSyncSetInput): Promise<ReplicationGroupState | null>;
+    /** Marks one node as being taken out of service, rebuilt, or quarantined. */
     updateNodeMaintenance(input: UpdateNodeMaintenanceInput): Promise<ReplicationGroupState | null>;
+    /** Promotes whichever in-sync replica is safe to write. */
     promoteEligibleReplica(input: PromoteEligibleReplicaInput): Promise<ReplicationGroupState>;
+    /** Closes the etcd client and stops every watch. */
     close(): Promise<void>;
-    private discardSupersededLeases;
     private getLeaseFromKey;
-    private trackLease;
 }
+/**
+ * @public
+ *
+ * Builds a coordinator backed by etcd.
+ *
+ * @param options - etcd endpoints, key prefix, credentials, and timeouts.
+ * @returns The coordinator, ready to pass to a replication engine.
+ */
 declare function createEtcdCoordinator(options: EtcdClusterCoordinatorOptions): EtcdClusterCoordinator;
 
 export { EtcdClusterCoordinator, type EtcdClusterCoordinatorOptions, createEtcdCoordinator };

package/dist/replication/coordinator/etcd.mjs

@@ -1,7 +1,7 @@
 import { compatibilityAllowsPromotion } from '../../chunk-ER7ODTDA.mjs';
-import { CoordinatorError, NoSafePrimaryError } from '../../chunk-O7SLN3GI.mjs';
-import '../../chunk-5NOIGN5Y.mjs';
-import '../../chunk-UC3SCMIN.mjs';
+import { CoordinatorError, NoSafePrimaryError } from '../../chunk-BTTFW4Z4.mjs';
+import '../../chunk-2QLXDHAP.mjs';
+import '../../chunk-PBRXXISQ.mjs';
 import { Etcd3 } from 'etcd3';
 
 // src/replication/coordinator/group-rules.ts
@@ -473,12 +473,65 @@ var EtcdGroupStore = class {
   }
 };
 
+// src/replication/coordinator/etcd-lease-registry.ts
+async function revokeLeaseQuietly(lease) {
+  try {
+    await lease.revoke();
+  } catch {
+    lease.release();
+  }
+}
+var EtcdLeaseRegistry = class {
+  constructor(onLeaseLost) {
+    this.onLeaseLost = onLeaseLost;
+  }
+  entries = /* @__PURE__ */ new Map();
+  get(leaseId) {
+    return this.entries.get(leaseId);
+  }
+  forget(leaseId) {
+    this.entries.delete(leaseId);
+  }
+  leaseIdsForKey(key) {
+    const matches = [];
+    for (const [leaseId, entry] of this.entries) {
+      if (entry.key === key) matches.push(leaseId);
+    }
+    return matches;
+  }
+  track(lease, entry) {
+    this.entries.set(entry.leaseId, { ...entry, lease });
+    lease.on("lost", (err) => {
+      this.entries.delete(entry.leaseId);
+      this.onLeaseLost?.(err instanceof Error ? err : new CoordinatorError(String(err)));
+    });
+  }
+  async discardSuperseded(key, keepLeaseId) {
+    const superseded = [];
+    for (const [leaseId, entry] of this.entries) {
+      if (entry.key === key && leaseId !== keepLeaseId) {
+        this.entries.delete(leaseId);
+        superseded.push(entry);
+      }
+    }
+    await Promise.allSettled(superseded.map((entry) => revokeLeaseQuietly(entry.lease)));
+  }
+  async revokeAll() {
+    const revokes = [];
+    for (const entry of this.entries.values()) {
+      revokes.push(revokeLeaseQuietly(entry.lease));
+    }
+    this.entries.clear();
+    await Promise.allSettled(revokes);
+  }
+};
+
 // src/replication/coordinator/etcd.ts
 var EtcdClusterCoordinator = class {
   client;
   namespace;
   onWatcherError;
-  leases = /* @__PURE__ */ new Map();
+  leases;
   grantedNodeSessionLeaseIds = /* @__PURE__ */ new Map();
   watchers = /* @__PURE__ */ new Set();
   groups;
@@ -487,8 +540,10 @@ var EtcdClusterCoordinator = class {
     this.client = new Etcd3(toEtcdOptions(options));
     this.namespace = this.client.namespace(normaliseKeyPrefix(options.keyPrefix));
     this.onWatcherError = options.onWatcherError;
+    this.leases = new EtcdLeaseRegistry(this.onWatcherError);
     this.groups = new EtcdGroupStore(this.namespace, this.watchers, this.onWatcherError);
   }
+  /** Bids for the controller lease, and reports who holds it. */
   async tryAcquireControllerLease(input) {
     assertNonEmpty(input.clusterId, "clusterId");
     assertNonEmpty(input.holderId, "holderId");
@@ -513,7 +568,7 @@ var EtcdClusterCoordinator = class {
       const current = await this.getLeaseFromKey(key);
       return { acquired: false, lease: current };
     }
-    this.trackLease(lease, {
+    this.leases.track(lease, {
       leaseId,
       key,
       ttlMs: input.ttlMs,
@@ -526,6 +581,7 @@ var EtcdClusterCoordinator = class {
     const parsed = parseLease(value);
     return { acquired: true, lease: parsed };
   }
+  /** Extends a lease, and reports false once it has already lapsed. */
   async renewLease(leaseId, ttlMs) {
     assertNonEmpty(leaseId, "leaseId");
     assertPositiveTtl(ttlMs);
@@ -536,7 +592,7 @@ var EtcdClusterCoordinator = class {
     try {
       await entry.lease.keepaliveOnce();
     } catch {
-      this.leases.delete(leaseId);
+      this.leases.forget(leaseId);
       return false;
     }
     const renewedAtMs = Date.now();
@@ -559,19 +615,20 @@ var EtcdClusterCoordinator = class {
       return true;
     }
     if (!refreshed) {
-      this.leases.delete(leaseId);
+      this.leases.forget(leaseId);
       return false;
     }
     entry.ttlMs = ttlMs;
     return true;
   }
+  /** Gives up a lease at once instead of waiting for it to lapse. */
   async releaseLease(leaseId) {
     assertNonEmpty(leaseId, "leaseId");
     const entry = this.leases.get(leaseId);
     if (!entry) {
       return false;
     }
-    this.leases.delete(leaseId);
+    this.leases.forget(leaseId);
     const currentValue = await this.namespace.get(entry.key).string();
     const currentLeaseId = currentValue ? parseLeaseIdForEntry(entry.kind, currentValue) : null;
     let released = false;
@@ -582,6 +639,7 @@ var EtcdClusterCoordinator = class {
     await revokeLeaseQuietly(entry.lease);
     return released;
   }
+  /** Records one node as a live member of the cluster. */
   async registerNodeSession(input) {
     assertNonEmpty(input.clusterId, "clusterId");
     assertNonEmpty(input.nodeId, "nodeId");
@@ -625,9 +683,9 @@ var EtcdClusterCoordinator = class {
       await revokeLeaseQuietly(lease);
       throw new CoordinatorError(`Node session '${input.nodeId}' registration conflicted with a concurrent write`);
     }
-    await this.discardSupersededLeases(key, leaseId);
+    await this.leases.discardSuperseded(key, leaseId);
     this.grantedNodeSessionLeaseIds.set(key, leaseId);
-    this.trackLease(lease, {
+    this.leases.track(lease, {
       leaseId,
       key,
       ttlMs: input.ttlMs,
@@ -649,46 +707,54 @@ var EtcdClusterCoordinator = class {
     });
     return parseNodeSession(rawSession);
   }
+  /** Reads one node's session, and returns null once its lease has lapsed. */
   async getLiveNodeSession(clusterId, nodeId) {
     assertNonEmpty(clusterId, "clusterId");
     assertNonEmpty(nodeId, "nodeId");
     const value = await this.namespace.get(nodeSessionKey(clusterId, nodeId)).string();
     return value ? parseNodeSession(value) : null;
   }
+  /** Ends one node's membership at once. */
   async deregisterNodeSession(clusterId, nodeId) {
     assertNonEmpty(clusterId, "clusterId");
     assertNonEmpty(nodeId, "nodeId");
-    const key = nodeSessionKey(clusterId, nodeId);
-    for (const [leaseId, entry] of this.leases) {
-      if (entry.key === key) {
-        await this.releaseLease(leaseId);
-      }
+    for (const leaseId of this.leases.leaseIdsForKey(nodeSessionKey(clusterId, nodeId))) {
+      await this.releaseLease(leaseId);
     }
   }
+  /** Writes the group's state, which seeds a new group or replaces an existing one. */
   setReplicationGroupState(input) {
     return this.groups.setReplicationGroupState(input);
   }
+  /** Reads the group's state, and returns null when the group is absent. */
   getReplicationGroupState(clusterId, groupId) {
     return this.groups.getReplicationGroupState(clusterId, groupId);
   }
+  /** Calls back on each change to the group's state, and returns a function that stops the watch. */
   watchReplicationGroup(clusterId, groupId, watcher) {
     return this.groups.watchReplicationGroup(clusterId, groupId, watcher);
   }
+  /** Promotes a node only while the group is still at the term the caller read. */
   compareAndAdvancePrimaryTerm(input) {
     return this.groups.compareAndAdvancePrimaryTerm(input);
   }
+  /** Replaces the group's in-sync set, and optionally moves its durability point. */
   updateInSyncSet(input) {
     return this.groups.updateInSyncSet(input);
   }
+  /** Adds one caught-up node to the in-sync set. */
   admitNodeToInSyncSet(input) {
     return this.groups.admitNodeToInSyncSet(input);
   }
+  /** Marks one node as being taken out of service, rebuilt, or quarantined. */
   updateNodeMaintenance(input) {
     return this.groups.updateNodeMaintenance(input);
   }
+  /** Promotes whichever in-sync replica is safe to write. */
   promoteEligibleReplica(input) {
     return this.groups.promoteEligibleReplica(input);
   }
+  /** Closes the etcd client and stops every watch. */
   async close() {
     const watcherCancels = [];
     for (const watcher of this.watchers) {
@@ -696,47 +762,17 @@ var EtcdClusterCoordinator = class {
     }
     this.watchers.clear();
     await Promise.allSettled(watcherCancels);
-    const leaseRevokes = [];
-    for (const entry of this.leases.values()) {
-      leaseRevokes.push(revokeLeaseQuietly(entry.lease));
-    }
-    this.leases.clear();
     this.grantedNodeSessionLeaseIds.clear();
-    await Promise.allSettled(leaseRevokes);
+    await this.leases.revokeAll();
     this.client.close();
   }
-  async discardSupersededLeases(key, keepLeaseId) {
-    const superseded = [];
-    for (const [leaseId, entry] of this.leases) {
-      if (entry.key === key && leaseId !== keepLeaseId) {
-        this.leases.delete(leaseId);
-        superseded.push(entry);
-      }
-    }
-    await Promise.allSettled(superseded.map((entry) => revokeLeaseQuietly(entry.lease)));
-  }
   async getLeaseFromKey(key) {
     const value = await this.namespace.get(key).string();
     return value ? parseLease(value) : null;
   }
-  trackLease(lease, entry) {
-    const fullEntry = { ...entry, lease };
-    this.leases.set(entry.leaseId, fullEntry);
-    lease.on("lost", (err) => {
-      this.leases.delete(entry.leaseId);
-      this.onWatcherError?.(err instanceof Error ? err : new CoordinatorError(String(err)));
-    });
-  }
 };
 function createEtcdCoordinator(options) {
   return new EtcdClusterCoordinator(options);
 }
-async function revokeLeaseQuietly(lease) {
-  try {
-    await lease.revoke();
-  } catch {
-    lease.release();
-  }
-}
 
 export { EtcdClusterCoordinator, createEtcdCoordinator };