@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/react/index.d.ts

@@ -1,10 +1,10 @@
-import { L as LiveQueryOptions, a as LiveQuery, b as LiveQueryState } from '../types-DTO4CYhW.js';
-import { O as OperationRef } from '../operation-registry-oiPuSYI6.js';
-import { P as Params } from '../query-types-p1liOP-b.js';
+import { L as LiveQueryOptions, a as LiveQuery, b as LiveQueryState } from '../types-CEJG0eFS.js';
+import { O as OperationRef } from '../operation-registry-CGhNT-Sn.js';
+import { P as Params } from '../query-types-5B02ixH0.js';
 
 /**
- * The one method these hooks need from a database, so both a local
- * `Database` and a `RemoteDatabase` satisfy it.
+ * The one database method that `useLiveQuery` calls, which both a local
+ * `Database` and a `RemoteDatabase` provide.
  *
  * @public
  */
@@ -18,31 +18,31 @@ interface LiveDatabase {
  * @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. */
+    /** Set it to `false` to keep the query closed, for example while the query's arguments depend on data that the component is still loading. */
     enabled?: boolean;
 }
 /**
- * Subscribes a component to a registered read and re-renders it as the rows change.
+ * Returns the state of a live query for a registered read, and re-renders the component each time the rows change.
  *
- * The query closes when the component unmounts.
+ * The hook closes the query 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.
+ * @param database - The database on which Sirannon runs the read.
+ * @param operation - The name of the registered read.
+ * @param args - The arguments for the read.
+ * @param options - The `enabled` flag and the live-query settings.
+ * @returns The query state, which is pending, ready with rows, or an error.
  *
  * @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.
+ * Returns the state of a live query for a registered read, and re-renders the component each time 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.
+ * @param database - The database on which Sirannon runs the read.
+ * @param operation - A reference to the registered read, with its argument and row types.
+ * @param args - The arguments for the read.
+ * @param options - The `enabled` flag and the live-query settings.
+ * @returns The query state, which is pending, ready with rows, or an error.
  *
  * @public
  */
@@ -50,8 +50,8 @@ declare function useLiveQuery<Args, Row>(database: LiveDatabase, operation: Oper
 /**
  * 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.
+ * @param database - The database on which Sirannon runs the write.
+ * @param command - A reference to the registered write, with its argument type.
  * @returns A callback that takes the write's arguments and resolves with its result.
  *
  * @public
@@ -62,7 +62,7 @@ declare function useCommand<Args, Result>(database: {
 /**
  * Returns a stable callback that runs a statement or a registered write by name.
  *
- * @param database - Database the write runs against.
+ * @param database - The database on which Sirannon runs the write.
  * @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.
  *

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

@@ -1,46 +1,49 @@
 import { IOptions } from 'etcd3';
-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-B0EhgDbr.js';
+import { C as ClusterCoordinator, A as AcquireControllerLeaseInput, a as AcquireControllerLeaseResult, b as ControllerLeaseWatcher, c as CoordinatorWatchDisposer, R as RegisterNodeSessionInput, d as CoordinatorNodeSession, N as NodeSessionWatcher, S as SetReplicationGroupStateInput, e as ReplicationGroupState, f as ReplicationGroupWatcher, g as CompareAndAdvancePrimaryTermInput, h as CompareAndAdvancePrimaryTermResult, U as UpdateInSyncSetInput, i as AdmitNodeToInSyncSetInput, j as UpdateNodeMaintenanceInput, P as PromoteEligibleReplicaInput } from '../../types-guEKSzMr.js';
 
 /**
- * Where the etcd coordinator connects, under which key prefix it stores group state, and how it authenticates.
+ * Sets the etcd endpoints that the etcd coordinator connects to, the key prefix that it stores group state under, and
+ * how it authenticates.
  *
  * @public
  */
 interface EtcdClusterCoordinatorOptions {
     /**
-     * etcd endpoints to connect to. Production access requires https addresses.
+     * Lists the etcd endpoints to connect to. The coordinator accepts only https endpoints unless `allowInsecure` is true.
      */
     hosts: string | string[];
     /**
-     * Prefix applied to every key this coordinator writes, which keeps clusters apart in one etcd.
+     * Sets the prefix that this coordinator puts in front of every key that it writes, so that several deployments can
+     * share one etcd.
      */
     keyPrefix: string;
     /**
-     * TLS material, which production access requires.
+     * Holds the TLS material, which the coordinator requires unless `allowInsecure` is true.
      */
     credentials?: IOptions['credentials'];
     /**
-     * Username and password, as an alternative to a client certificate.
+     * Holds a username and password, which the coordinator accepts in place of a client certificate.
      */
     auth?: IOptions['auth'];
     /**
-     * Options passed straight through to the underlying gRPC channel.
+     * Holds options that the coordinator passes unchanged to the underlying gRPC channel.
      */
     grpcOptions?: IOptions['grpcOptions'];
     /**
-     * Milliseconds to wait for a connection to etcd.
+     * Sets how many milliseconds the client waits to connect to etcd.
      */
     dialTimeoutMs?: number;
     /**
-     * Milliseconds any single etcd call may take.
+     * Sets how many milliseconds a single etcd call can take before its deadline expires.
      */
     defaultCallTimeoutMs?: number;
     /**
-     * Accepts plain http endpoints without credentials, which suits tests only.
+     * Lets the coordinator connect to plain http endpoints without credentials. Use it only in tests.
      */
     allowInsecure?: boolean;
     /**
-     * Called when a group watch fails so that a caller can log it or raise an alert.
+     * Receives each error that an etcd watch reports or that a watch callback throws, and each lost lease, so that you
+     * can log it or raise an alert.
      */
     onWatcherError?: (error: Error) => void;
 }
@@ -48,55 +51,58 @@ interface EtcdClusterCoordinatorOptions {
 /**
  * Stores primary authority, node sessions, group state, and the in-sync set in etcd.
  *
- * Build one with {@link createEtcdCoordinator}.
+ * Build one with {@link createEtcdCoordinator}. The coordinator loads the `etcd3` package the first time that one of its methods connects to etcd. When this process cannot load that package, the call fails with a `SirannonError` whose code is `COORDINATOR_DEPENDENCY_MISSING`.
  *
  * @public
  */
 declare class EtcdClusterCoordinator implements ClusterCoordinator {
-    private readonly client;
-    private readonly namespace;
+    private readonly options;
+    private connection;
     private readonly onWatcherError;
     private readonly leases;
     private readonly grantedNodeSessionLeaseIds;
     private readonly watchers;
-    private readonly groups;
     constructor(options: EtcdClusterCoordinatorOptions);
-    /** Bids for the controller lease, and reports who holds it. */
+    /** Tries to acquire the controller lease, and returns whether it succeeded along with the current lease. */
     tryAcquireControllerLease(input: AcquireControllerLeaseInput): Promise<AcquireControllerLeaseResult>;
-    /** Extends a lease, and reports false once it has already lapsed. */
+    /** Calls `watcher` with the current controller lease when the watch starts and after each change, and returns a function that stops the watch. */
+    watchControllerLease(clusterId: string, watcher: ControllerLeaseWatcher): Promise<CoordinatorWatchDisposer>;
+    /** Extends a lease, and returns false for a lease that is expired or unknown to this coordinator. */
     renewLease(leaseId: string, ttlMs: number): Promise<boolean>;
-    /** Gives up a lease at once instead of waiting for it to lapse. */
+    /** Deletes a lease's key if the key still refers to that lease, then revokes the lease, and returns whether the delete succeeded. */
     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. */
+    /** Returns one node's session, or null once its lease expires. */
     getLiveNodeSession(clusterId: string, nodeId: string): Promise<CoordinatorNodeSession | null>;
-    /** Ends one node's membership at once. */
+    /** Calls `watcher` with the IDs of every node that holds a live session, and returns a function that stops the watch. */
+    watchNodeSessions(clusterId: string, watcher: NodeSessionWatcher): Promise<CoordinatorWatchDisposer>;
+    /** Ends one node's session at once by releasing its leases. */
     deregisterNodeSession(clusterId: string, nodeId: string): Promise<void>;
-    /** Writes the group's state, which seeds a new group or replaces an existing one. */
+    /** Writes the group's state, which creates 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. */
+    /** Returns the group's state, or null when etcd has no state for the group. */
     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. */
+    /** Calls `watcher` with the new state after each change to the group, 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. */
+    /** Makes a node primary and advances the term, but only while the group is still at the term that the caller expects. */
     compareAndAdvancePrimaryTerm(input: CompareAndAdvancePrimaryTermInput): Promise<CompareAndAdvancePrimaryTermResult>;
-    /** Replaces the group's in-sync set, and optionally moves its durability point. */
+    /** Replaces the group's in-sync set with a subset of it, and can advance the 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. */
+    /** Sets or clears one node's draining, repairing, and faulted flags. */
     updateNodeMaintenance(input: UpdateNodeMaintenanceInput): Promise<ReplicationGroupState | null>;
-    /** Promotes whichever in-sync replica is safe to write. */
+    /** Promotes an eligible in-sync replica, and throws a `NoSafePrimaryError` when no replica qualifies. */
     promoteEligibleReplica(input: PromoteEligibleReplicaInput): Promise<ReplicationGroupState>;
-    /** Closes the etcd client and stops every watch. */
+    /** Stops every watch, revokes every lease that this coordinator granted, and closes the etcd client. */
     close(): Promise<void>;
-    private getLeaseFromKey;
+    private connect;
 }
 /**
- * Builds a coordinator backed by etcd.
+ * Returns a new coordinator that stores its state in etcd.
  *
- * @param options - etcd endpoints, key prefix, credentials, and timeouts.
+ * @param options - The etcd endpoints, key prefix, credentials, and timeouts.
  * @returns The coordinator, ready to pass to a replication engine.
  *
  * @public