@cortexkit/common-auth 0.1.3 → 0.2.0

package/dist/store/mutate.d.ts

@@ -0,0 +1,111 @@
+import { type PoolFailurePhase, type PoolOperation, PoolOperationError } from './errors.js';
+import { type PoolLogger } from './hooks.js';
+import { type LockEnvironment, LockStack, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
+import { type PoolRow, type QuotaCodec, type StoredCredential } from './schema.js';
+/** Named points on the write path, for crash and ownership injection. */
+export type WriteStep = 'before-config-write' | 'after-config-write' | 'before-state-write' | 'after-state-write';
+/** Awaitable pause points on the pull and refresh paths. */
+export type HoldPoint = 'refresh-before-provider' | 'pull-before-request';
+export interface StoreContext {
+    provider: string;
+    configPath: string;
+    statePath: string;
+    codec: QuotaCodec;
+    now: () => number;
+    storeLocks: readonly PoolLockSpec[];
+    lockDefaults: PoolLockOptions;
+    lockEnv: LockEnvironment;
+    logger?: PoolLogger;
+    onStep?: (step: WriteStep, info: {
+        operation: PoolOperation;
+        rowId: string | undefined;
+    }) => void | Promise<void>;
+    hold?: (point: HoldPoint, rowId: string) => void | Promise<void>;
+    /** Ids whose per-row entry a library write dropped in this process. */
+    removedIds: Set<string>;
+}
+export interface Snapshot {
+    configExists: boolean;
+    stateExists: boolean;
+    config: Record<string, unknown>;
+    state: Record<string, unknown>;
+    rows: PoolRow[];
+}
+export type ReadResult = ({
+    status: 'ready';
+} & Snapshot) | {
+    status: 'pending-migration';
+    config: Record<string, unknown>;
+} | {
+    status: 'error';
+    file: 'config' | 'state';
+    reason: string;
+};
+/** Reads and classifies both files. Never writes. */
+export declare function readPool(ctx: StoreContext): Promise<ReadResult>;
+/** The refusal for a pool that is not ready, as a failure value. */
+export declare function notReadyError(result: Exclude<ReadResult, {
+    status: 'ready';
+}>, operation: PoolOperation, rowId: string | undefined, phase?: PoolFailurePhase): PoolOperationError;
+/** What an operation has written so far; decides the failure phase. */
+export interface Progress {
+    writes: number;
+    /** The credential the operation's state write put on disk, once it has. */
+    committed?: StoredCredential;
+}
+/**
+ * One locked read-modify-write. The store locks are pushed onto the caller's
+ * lock stack, so the ownership assertion before each write covers the outer
+ * row, provider-wide and extra locks as well; they are released when the
+ * transaction ends, whatever happens.
+ */
+export declare class Transaction {
+    private readonly ctx;
+    readonly snapshot: Snapshot;
+    private readonly locks;
+    private readonly progress;
+    private readonly info;
+    config: Record<string, unknown>;
+    state: Record<string, unknown>;
+    constructor(ctx: StoreContext, snapshot: Snapshot, locks: LockStack, progress: Progress, info: {
+        operation: PoolOperation;
+        rowId: string | undefined;
+    });
+    rows(): PoolRow[];
+    row(id: string): PoolRow | undefined;
+    roster(): unknown[];
+    /** The first roster row with this id (the one the pool loads). */
+    rosterRow(id: string): Record<string, unknown> | undefined;
+    entries(): Record<string, unknown>;
+    entry(id: string): Record<string, unknown> | undefined;
+    setEntry(id: string, entry: Record<string, unknown>): void;
+    stateAccount(id: string): Record<string, unknown> | undefined;
+    setStateAccount(id: string, fields: Record<string, unknown>): void;
+    /**
+     * Writes the config: legacy `version: 1` and the legacy roster beside
+     * `commonAuthPool`, every other top-level key and every unrecognised pool
+     * key untouched. Entries for ids no longer in the roster are dropped here,
+     * and remembered so the id is not reused in this process.
+     */
+    commitConfig(): Promise<void>;
+    /** Writes the state: every unrecognised top-level and per-row key kept. */
+    commitState(committed?: StoredCredential): Promise<void>;
+    private write;
+}
+/**
+ * Runs `fn` under the store-lock list. The pool must be ready: a pending
+ * migration or a load error refuses before anything is written.
+ */
+export declare function withTransaction<T>(ctx: StoreContext, locks: LockStack, progress: Progress, info: {
+    operation: PoolOperation;
+    rowId: string | undefined;
+}, fn: (tx: Transaction) => Promise<T>): Promise<T>;
+/** Maps anything thrown inside an operation onto the one failure value. */
+export declare function toFailure(error: unknown, operation: PoolOperation, rowId: string | undefined, progress: Progress): PoolOperationError;
+/**
+ * The frame every lock-holding operation runs in: failures are mapped onto
+ * the failure value, handed to the failure hook while the outer locks are
+ * still held (the store locks are already released), and rethrown; every
+ * lock is released afterwards.
+ */
+export declare function runOperation<T>(ctx: StoreContext, operation: PoolOperation, rowId: string, onFailure: ((rowId: string, error: PoolOperationError) => void | Promise<void>) | undefined, body: (locks: LockStack, progress: Progress) => Promise<T>): Promise<T>;

package/dist/store/mutate.js

@@ -0,0 +1,294 @@
+import { readFile } from 'node:fs/promises';
+import { writeJsonAtomic } from '../fs/atomic-write.js';
+import { LockContentionError, LockOwnershipError } from '../fs/with-lock.js';
+import { PoolOperationError, } from './errors.js';
+import { callFailureHook } from './hooks.js';
+import { LockStack, } from './refresh-lock.js';
+import { buildRows, classifyConfig, classifyState, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, } from './schema.js';
+async function readJson(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { exists: false };
+        throw error;
+    }
+    try {
+        return { exists: true, value: JSON.parse(text) };
+    }
+    catch (parseError) {
+        return { exists: true, parseError };
+    }
+}
+/** Reads and classifies both files. Never writes. */
+export async function readPool(ctx) {
+    const config = classifyConfig(await readJson(ctx.configPath));
+    if (config.status === 'error')
+        return { status: 'error', file: 'config', reason: config.reason };
+    const state = classifyState(await readJson(ctx.statePath));
+    if (state.status === 'error')
+        return { status: 'error', file: 'state', reason: state.reason };
+    if (config.status === 'pending-migration')
+        return { status: 'pending-migration', config: config.config };
+    return {
+        status: 'ready',
+        configExists: config.exists,
+        stateExists: state.exists,
+        config: config.config,
+        state: state.state,
+        rows: buildRows(config.config, state.state, ctx.codec),
+    };
+}
+/** The refusal for a pool that is not ready, as a failure value. */
+export function notReadyError(result, operation, rowId, phase = 'before-first-write') {
+    return new PoolOperationError({
+        operation,
+        ...(rowId !== undefined ? { rowId } : {}),
+        phase,
+        retryable: false,
+        kind: result.status === 'pending-migration'
+            ? 'pending-migration'
+            : 'load-error',
+        message: result.status === 'pending-migration'
+            ? 'the config holds a legacy roster that has not been migrated into the pool'
+            : `${result.file} file cannot be loaded: ${result.reason}`,
+    });
+}
+/**
+ * One locked read-modify-write. The store locks are pushed onto the caller's
+ * lock stack, so the ownership assertion before each write covers the outer
+ * row, provider-wide and extra locks as well; they are released when the
+ * transaction ends, whatever happens.
+ */
+export class Transaction {
+    ctx;
+    snapshot;
+    locks;
+    progress;
+    info;
+    config;
+    state;
+    constructor(ctx, snapshot, locks, progress, info) {
+        this.ctx = ctx;
+        this.snapshot = snapshot;
+        this.locks = locks;
+        this.progress = progress;
+        this.info = info;
+        this.config = structuredClone(snapshot.config);
+        this.state = structuredClone(snapshot.state);
+    }
+    rows() {
+        return buildRows(this.config, this.state, this.ctx.codec);
+    }
+    row(id) {
+        return this.rows().find((row) => row.id === id);
+    }
+    roster() {
+        if (!Array.isArray(this.config.accounts))
+            this.config.accounts = [];
+        return this.config.accounts;
+    }
+    /** The first roster row with this id (the one the pool loads). */
+    rosterRow(id) {
+        return this.roster().find((raw) => isRecord(raw) && raw.id === id);
+    }
+    entries() {
+        if (!isRecord(this.config[POOL_KEY]))
+            this.config[POOL_KEY] = {};
+        const pool = this.config[POOL_KEY];
+        if (!isRecord(pool[POOL_ROWS_KEY]))
+            pool[POOL_ROWS_KEY] = {};
+        return pool[POOL_ROWS_KEY];
+    }
+    entry(id) {
+        const entries = this.entries();
+        const entry = Object.hasOwn(entries, id) ? entries[id] : undefined;
+        return isRecord(entry) ? entry : undefined;
+    }
+    setEntry(id, entry) {
+        Object.defineProperty(this.entries(), id, {
+            value: entry,
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    stateAccount(id) {
+        const accounts = isRecord(this.state.accounts) ? this.state.accounts : {};
+        const entry = Object.hasOwn(accounts, id) ? accounts[id] : undefined;
+        return isRecord(entry) ? entry : undefined;
+    }
+    setStateAccount(id, fields) {
+        if (!isRecord(this.state.accounts))
+            this.state.accounts = {};
+        Object.defineProperty(this.state.accounts, id, {
+            value: fields,
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    /**
+     * Writes the config: legacy `version: 1` and the legacy roster beside
+     * `commonAuthPool`, every other top-level key and every unrecognised pool
+     * key untouched. Entries for ids no longer in the roster are dropped here,
+     * and remembered so the id is not reused in this process.
+     */
+    async commitConfig() {
+        const roster = this.roster();
+        const rosterIds = new Set();
+        for (const raw of roster)
+            if (isRecord(raw) && typeof raw.id === 'string')
+                rosterIds.add(raw.id);
+        const entries = this.entries();
+        const kept = {};
+        for (const [id, entry] of Object.entries(entries)) {
+            if (rosterIds.has(id)) {
+                Object.defineProperty(kept, id, {
+                    value: entry,
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+            }
+            else {
+                this.ctx.removedIds.add(id);
+            }
+        }
+        const pool = this.config[POOL_KEY];
+        const next = {
+            ...this.config,
+            version: LEGACY_STORE_VERSION,
+            accounts: roster,
+            [POOL_KEY]: {
+                ...pool,
+                schemaVersion: POOL_SCHEMA_VERSION,
+                [POOL_ROWS_KEY]: kept,
+            },
+        };
+        await this.write(this.ctx.configPath, next, 'config');
+        this.config = next;
+    }
+    /** Writes the state: every unrecognised top-level and per-row key kept. */
+    async commitState(committed) {
+        const next = {
+            ...this.state,
+            version: LEGACY_STORE_VERSION,
+            accounts: isRecord(this.state.accounts) ? this.state.accounts : {},
+        };
+        await this.write(this.ctx.statePath, next, 'state');
+        this.state = next;
+        if (committed)
+            this.progress.committed = committed;
+    }
+    async write(path, value, file) {
+        await writeJsonAtomic(path, value, {
+            beforeRename: async () => {
+                await this.ctx.onStep?.(`before-${file}-write`, this.info);
+                // Ownership is proved immediately before the rename, on every lease.
+                await this.locks.assertAll();
+            },
+        });
+        this.progress.writes++;
+        await this.ctx.onStep?.(`after-${file}-write`, this.info);
+    }
+}
+/**
+ * Runs `fn` under the store-lock list. The pool must be ready: a pending
+ * migration or a load error refuses before anything is written.
+ */
+export async function withTransaction(ctx, locks, progress, info, fn) {
+    const mark = locks.held.length;
+    try {
+        for (const spec of ctx.storeLocks)
+            await locks.acquire(spec);
+        const result = await readPool(ctx);
+        if (result.status !== 'ready')
+            throw notReadyError(result, info.operation, info.rowId, progress.writes > 0 ? 'after-first-write' : 'before-first-write');
+        return await fn(new Transaction(ctx, result, locks, progress, info));
+    }
+    finally {
+        await locks.releaseTo(mark);
+    }
+}
+/** Maps anything thrown inside an operation onto the one failure value. */
+export function toFailure(error, operation, rowId, progress) {
+    const phase = operation === 'pull'
+        ? 'pull'
+        : progress.writes > 0
+            ? 'after-first-write'
+            : 'before-first-write';
+    const committed = phase === 'after-first-write' ? progress.committed : undefined;
+    if (error instanceof PoolOperationError) {
+        if (error.phase === phase &&
+            error.rowId === rowId &&
+            error.operation === operation &&
+            error.committed === committed)
+            return error;
+        return new PoolOperationError({
+            operation,
+            ...(rowId !== undefined ? { rowId } : {}),
+            phase: error.kind === 'after-persist-hook' ? error.phase : phase,
+            retryable: error.retryable,
+            kind: error.kind,
+            ...((error.committed ?? committed)
+                ? { committed: error.committed ?? committed }
+                : {}),
+            message: error.message,
+            ...(error.cause !== undefined ? { cause: error.cause } : {}),
+        });
+    }
+    const base = {
+        operation,
+        ...(rowId !== undefined ? { rowId } : {}),
+        phase,
+        ...(committed ? { committed } : {}),
+        cause: error,
+    };
+    if (error instanceof LockOwnershipError)
+        return new PoolOperationError({
+            ...base,
+            retryable: true,
+            kind: 'lock-ownership',
+            message: phase === 'after-first-write'
+                ? `${operation} lost a lease after its first write; the intermediate stays on disk`
+                : `${operation} lost a lease before writing; nothing was written`,
+        });
+    if (error instanceof LockContentionError)
+        return new PoolOperationError({
+            ...base,
+            retryable: true,
+            kind: 'lock-contention',
+            message: error.message,
+        });
+    return new PoolOperationError({
+        ...base,
+        retryable: false,
+        kind: 'unexpected',
+        message: error instanceof Error ? error.message : String(error),
+    });
+}
+/**
+ * The frame every lock-holding operation runs in: failures are mapped onto
+ * the failure value, handed to the failure hook while the outer locks are
+ * still held (the store locks are already released), and rethrown; every
+ * lock is released afterwards.
+ */
+export async function runOperation(ctx, operation, rowId, onFailure, body) {
+    const locks = new LockStack(ctx.lockDefaults, ctx.lockEnv);
+    const progress = { writes: 0 };
+    try {
+        return await body(locks, progress);
+    }
+    catch (error) {
+        const failure = toFailure(error, operation, rowId, progress);
+        if (failure.kind !== 'after-persist-hook')
+            await callFailureHook(operation, onFailure, rowId, failure, ctx.logger);
+        throw failure;
+    }
+    finally {
+        await locks.releaseAll();
+    }
+}

package/dist/store/pool.d.ts

@@ -0,0 +1,86 @@
+import { type Attribution } from './attribution.js';
+import type { PoolOperationError } from './errors.js';
+import type { PoolLogger } from './hooks.js';
+import { type HoldPoint, type StoreContext } from './mutate.js';
+import { type PullHook } from './pull.js';
+import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from './refresh.js';
+import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
+import { type AddInput, type AddResult, type RowOperationOptions } from './rows.js';
+import { type PoolCredential, type PoolRow, type QuotaCodec, type StoredCredential } from './schema.js';
+export interface OpenPoolStoreOptions {
+    /** The provider every row of this pool belongs to; keys the provider-wide lock. */
+    provider: string;
+    configPath: string;
+    statePath: string;
+    quota: QuotaCodec;
+    /** Injected clock for leases, refresh stamps and `addedAt`. */
+    now?: () => number;
+    /**
+     * Ordered store-lock list held across every read-modify-write. Defaults to
+     * the older writers' `save` lock at the config path, then at the state path.
+     */
+    storeLocks?: readonly PoolLockSpec[];
+    /** Defaults for every lock the store takes (see `POOL_LOCK_DEFAULTS`). */
+    lockOptions?: Partial<PoolLockOptions>;
+    /** Overrides for the row locks only. */
+    rowLockOptions?: Partial<PoolLockOptions>;
+    /** The provider-wide lock; defaults to `provider-<provider>` beside the state file. */
+    providerLock?: PoolLockSpec;
+    /** Quota pull hook, fired without being awaited. */
+    pull?: PullHook;
+    /** Receives every pull failure, since no caller awaits a pull. */
+    onPullFailure?: (rowId: string, error: PoolOperationError) => void | Promise<void>;
+    logger?: PoolLogger;
+    /** Named write steps, awaited; a test seam for crash and ownership rows. */
+    onStep?: StoreContext['onStep'];
+    /** Awaitable hold points on the refresh and pull paths; a test seam. */
+    hold?: (point: HoldPoint, rowId: string) => void | Promise<void>;
+    onLockEvent?: LockEnvironment['onLockEvent'];
+    onLockStep?: LockEnvironment['onLockStep'];
+}
+export type PoolLoad = {
+    status: 'ready';
+    schemaVersion: number;
+    rows: PoolRow[];
+} | {
+    status: 'pending-migration';
+    roster: unknown[];
+} | {
+    status: 'error';
+    file: 'config' | 'state';
+    reason: string;
+};
+export interface PoolStore {
+    /** Reads the pool and fires first-reading pulls; never writes a file itself. */
+    load(): Promise<PoolLoad>;
+    /** Reads the pool without firing anything. */
+    read(): Promise<PoolLoad>;
+    add(input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
+    replace(id: string, credential: PoolCredential, input?: {
+        identity?: string;
+    }, options?: RowOperationOptions): Promise<{
+        id: string;
+        credential: StoredCredential;
+        credentialEpoch: number;
+    }>;
+    rotate(id: string, credential: PoolCredential, input?: {
+        identity?: string;
+    }, options?: RowOperationOptions): Promise<{
+        id: string;
+        credential: StoredCredential;
+    }>;
+    disable(id: string, reason: string, options?: Pick<RowOperationOptions, 'onFailure'>): Promise<{
+        id: string;
+    }>;
+    recordIdentity(id: string, identity: string, options?: RowOperationOptions): Promise<{
+        id: string;
+        disabled: string[];
+    }>;
+    refresh(id: string, provider: ProviderRefresh, options?: RefreshOptions): Promise<RefreshOutcome>;
+    recordQuota(id: string, attribution: Attribution, observation: unknown): Promise<void>;
+    /** Fires a pull for a row admission refused for want of a reading. */
+    requestReading(id: string): void;
+    /** Resolves once every pull fired so far has settled. */
+    pullsSettled(): Promise<void>;
+}
+export declare function openPoolStore(options: OpenPoolStoreOptions): PoolStore;

package/dist/store/pool.js

@@ -0,0 +1,98 @@
+import { recordQuota } from './attribution.js';
+import { readPool } from './mutate.js';
+import { PullScheduler } from './pull.js';
+import { refreshRow, } from './refresh.js';
+import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
+import { addRow, disableRow, recordRowIdentity, replaceRow, rotateRow, } from './rows.js';
+import { POOL_SCHEMA_VERSION, } from './schema.js';
+/**
+ * Process-wide memory per config file: ids whose per-row entry a library
+ * write dropped (not reused in this process), and rows a load-time pull
+ * already fired for.
+ */
+const processMemory = new Map();
+function memoryFor(configPath) {
+    let memory = processMemory.get(configPath);
+    if (!memory) {
+        memory = { removedIds: new Set(), firedAtLoad: new Set() };
+        processMemory.set(configPath, memory);
+    }
+    return memory;
+}
+function toLoad(result) {
+    if (result.status === 'ready')
+        return {
+            status: 'ready',
+            schemaVersion: POOL_SCHEMA_VERSION,
+            rows: result.rows,
+        };
+    if (result.status === 'pending-migration')
+        return {
+            status: 'pending-migration',
+            roster: Array.isArray(result.config.accounts)
+                ? result.config.accounts
+                : [],
+        };
+    return result;
+}
+export function openPoolStore(options) {
+    const memory = memoryFor(options.configPath);
+    const lockDefaults = {
+        ...POOL_LOCK_DEFAULTS,
+        ...options.lockOptions,
+    };
+    const ctx = {
+        provider: options.provider,
+        configPath: options.configPath,
+        statePath: options.statePath,
+        codec: options.quota,
+        now: options.now ?? Date.now,
+        storeLocks: options.storeLocks ?? [
+            { name: 'save', path: options.configPath },
+            { name: 'save', path: options.statePath },
+        ],
+        lockDefaults,
+        lockEnv: {
+            now: options.now ?? Date.now,
+            ...(options.onLockEvent ? { onLockEvent: options.onLockEvent } : {}),
+            ...(options.onLockStep ? { onLockStep: options.onLockStep } : {}),
+        },
+        removedIds: memory.removedIds,
+        ...(options.logger ? { logger: options.logger } : {}),
+        ...(options.onStep ? { onStep: options.onStep } : {}),
+        ...(options.hold ? { hold: options.hold } : {}),
+    };
+    const pulls = new PullScheduler(() => rt, options.pull, options.onPullFailure, memory.firedAtLoad, options.logger);
+    const rt = {
+        ctx,
+        providerLock: options.providerLock ?? {
+            name: `provider-${encodeURIComponent(options.provider)}`,
+            path: options.statePath,
+        },
+        rowLockOptions: options.rowLockOptions ?? {},
+        firePull: (id, reason) => pulls.fire(id, reason),
+    };
+    return {
+        async load() {
+            const result = await readPool(ctx);
+            if (result.status === 'ready') {
+                for (const row of result.rows)
+                    if (row.candidate && row.type === 'oauth' && row.needsFirstReading)
+                        pulls.fire(row.id, 'load');
+            }
+            return toLoad(result);
+        },
+        async read() {
+            return toLoad(await readPool(ctx));
+        },
+        add: (input, callOptions) => addRow(rt, input, callOptions),
+        replace: (id, credential, input, callOptions) => replaceRow(rt, id, credential, input, callOptions),
+        rotate: (id, credential, input, callOptions) => rotateRow(rt, id, credential, input, callOptions),
+        disable: (id, reason, callOptions) => disableRow(rt, id, reason, callOptions),
+        recordIdentity: (id, identity, callOptions) => recordRowIdentity(rt, id, identity, callOptions),
+        refresh: (id, provider, callOptions) => refreshRow(rt, id, provider, callOptions),
+        recordQuota: (id, attribution, observation) => recordQuota(rt, id, attribution, observation),
+        requestReading: (id) => pulls.fire(id, 'admission'),
+        pullsSettled: () => pulls.settled(),
+    };
+}

package/dist/store/pull.d.ts

@@ -0,0 +1,36 @@
+import { PoolOperationError } from './errors.js';
+import type { PoolLogger } from './hooks.js';
+import type { PullReason, StoreRuntime } from './runtime.js';
+import type { StoredCredential } from './schema.js';
+/** What a pull is issued with: the credential and its attribution tuple. */
+export interface PullRequest {
+    id: string;
+    credential: StoredCredential;
+    credentialEpoch: number;
+    identity?: string;
+    reason: PullReason;
+}
+export type PullHook = (request: PullRequest) => Promise<unknown>;
+/**
+ * Fires quota pulls without ever making a caller wait for one. A pull first
+ * gives a row without a per-row entry its entry at epoch 1 (its own locked
+ * config write), then captures the credential and the attribution tuple in
+ * one locked read, requests the observation, and records it only if
+ * attribution still holds. Failures go to the store's pull failure hook.
+ */
+export declare class PullScheduler {
+    private readonly rt;
+    private readonly hook;
+    private readonly onFailure;
+    /** Rows a load-time pull has fired for in this process. */
+    private readonly firedAtLoad;
+    private readonly logger;
+    private readonly inflight;
+    constructor(rt: () => StoreRuntime, hook: PullHook | undefined, onFailure: ((rowId: string, error: PoolOperationError) => void | Promise<void>) | undefined, 
+    /** Rows a load-time pull has fired for in this process. */
+    firedAtLoad: Set<string>, logger: PoolLogger | undefined);
+    fire(id: string, reason: PullReason): void;
+    /** Resolves once every pull fired so far has settled. */
+    settled(): Promise<void>;
+    private run;
+}