@eltjs/elt 0.0.0-stage → 0.1.1

package/dist/core/signal-watch.d.ts

@@ -0,0 +1,11 @@
+import { type Outcome } from '@zukhruf/async';
+import type { ChangeSignal } from './change-signal.ts';
+import type { PipelineClock } from './clock.ts';
+import type { FailureType } from './source.ts';
+import type { Stream } from './stream.ts';
+export declare function brokenSignals(signals: readonly ChangeSignal[], selected: readonly Stream[]): string | undefined;
+export declare function watchSignals(signals: readonly ChangeSignal[], options: {
+    readonly signal: AbortSignal;
+    readonly clock: PipelineClock;
+    readonly failureType: (error: unknown) => FailureType;
+}): AsyncGenerator<ReadonlyMap<string, Outcome>>;

package/dist/core/signal-watch.js

@@ -0,0 +1,110 @@
+import { ChangeWatcher, Gauge, } from '@zukhruf/async';
+import { interleave } from './interleave.js';
+// Why a source's change signals break the contract for the selected streams,
+// or undefined when they keep it: each selected stream is in one change
+// signal or more, no change signal names another stream, and the change
+// signals of one stream have one interval and one timeout.
+export function brokenSignals(signals, selected) {
+    const names = new Set(selected.map(({ name }) => name));
+    const paces = new Map();
+    for (const { streams, interval, timeout } of signals)
+        for (const { name } of streams) {
+            if (!names.has(name))
+                return `A change signal names an unselected stream: ${name}`;
+            const pace = `${interval}/${timeout}`;
+            const known = paces.get(name);
+            if (known !== undefined && known !== pace)
+                return `The change signals of stream ${name} have two intervals`;
+            paces.set(name, pace);
+        }
+    const missing = selected.find(({ name }) => !paces.has(name));
+    return missing === undefined
+        ? undefined
+        : `No change signal tells about stream ${missing.name}`;
+}
+// At each check of one interval, the outcome of each stream that the check
+// covered, by stream name: changed when one of its gauges changed, else
+// failed when one of them failed, else unchanged. Each interval and timeout
+// has its own change watcher, so a slow read is not made at each check of a
+// fast one (ADR 0020).
+export function watchSignals(signals, options) {
+    const paces = new Map();
+    for (const { gauge, streams, interval, timeout } of signals) {
+        const key = `${interval}/${timeout}`;
+        const pace = paces.get(key) ?? { interval, timeout, gauges: new Map() };
+        paces.set(key, pace);
+        const read = pace.gauges.get(gauge) ?? new SignalGauge(gauge, options.failureType);
+        pace.gauges.set(gauge, read);
+        read.streams.push(...streams.map(({ name }) => name));
+    }
+    return interleave([...paces.values()].map((pace) => watchPace(pace, options)), Number.POSITIVE_INFINITY);
+}
+async function* watchPace({ interval, timeout, gauges }, { signal, clock, }) {
+    const watcher = new ChangeWatcher(gauges.values(), {
+        interval,
+        timeout,
+        clock,
+    });
+    for await (const outcomes of watcher.watch(signal)) {
+        const ofStream = Map.groupBy([...outcomes].flatMap(([gauge, outcome]) => gauge.streams.map((name) => ({ name, outcome }))), ({ name }) => name);
+        yield new Map([...ofStream].map(([name, told]) => [
+            name,
+            combined(told.map(({ outcome }) => outcome)),
+        ]));
+    }
+}
+function combined(outcomes) {
+    return (outcomes.find(({ state }) => state === 'changed') ??
+        outcomes.find(({ state }) => state === 'failed') ?? { state: 'unchanged' });
+}
+// A gauge of a source as the pipeline reads it: the streams that it tells
+// about, in all the change signals of one interval, and no read after a
+// failure that only the user can fix, as such a failure stopped the whole
+// connection before: a refused login is not tried again at each check. A new
+// watch reads it again (ADR 0020).
+class SignalGauge extends Gauge {
+    streams = [];
+    #state;
+    constructor(gauge, failureType) {
+        super();
+        this.#state = new Reading(gauge, failureType);
+    }
+    async read(check) {
+        const { result, next } = await this.#state.read(check);
+        this.#state = next;
+        if (result.status === 'rejected')
+            throw result.reason;
+        return result.value;
+    }
+}
+// Reads the gauge, and halts after a failure of the config type.
+class Reading {
+    #gauge;
+    #failureType;
+    constructor(gauge, failureType) {
+        this.#gauge = gauge;
+        this.#failureType = failureType;
+    }
+    async read(check) {
+        try {
+            const value = await this.#gauge.value(check);
+            return { result: { status: 'fulfilled', value }, next: this };
+        }
+        catch (reason) {
+            return {
+                result: { status: 'rejected', reason },
+                next: this.#failureType(reason) === 'config' ? new Halted(reason) : this,
+            };
+        }
+    }
+}
+// Gives the failure that halted it, and reads nothing.
+class Halted {
+    #reason;
+    constructor(reason) {
+        this.#reason = reason;
+    }
+    async read() {
+        return { result: { status: 'rejected', reason: this.#reason }, next: this };
+    }
+}

package/dist/core/snapshot.d.ts

@@ -0,0 +1,17 @@
+import { DeletionPolicy, type KeptGroup, type SnapshotGroup } from '@zukhruf/snapshot-differential';
+import type { CopyConfiguration } from './copy-configuration.ts';
+import type { DeleteMessage, StateMessage } from './source.ts';
+export type { KeptGroup };
+export type SnapshotDiffOptions = {
+    readonly policy?: DeletionPolicy;
+    readonly continues?: boolean;
+    readonly signal: AbortSignal | undefined;
+};
+type SnapshotMessage<Data> = {
+    readonly stream: string;
+    readonly data: Data;
+} | DeleteMessage | StateMessage;
+export declare function diffSnapshot<Data extends Record<string, unknown>>({ stream, syncMode }: CopyConfiguration, records: AsyncIterable<Data> | Iterable<Data>, state: unknown, options: SnapshotDiffOptions & {
+    readonly rereads?: (record: Data) => boolean;
+}): AsyncGenerator<SnapshotMessage<Data>>;
+export declare function diffGroupedSnapshot<Data extends Record<string, unknown>>({ stream, syncMode }: CopyConfiguration, groups: AsyncIterable<SnapshotGroup<Data> | KeptGroup> | Iterable<SnapshotGroup<Data> | KeptGroup>, state: unknown, options: SnapshotDiffOptions): AsyncGenerator<SnapshotMessage<Data>>;

package/dist/core/snapshot.js

@@ -0,0 +1,111 @@
+import { DeletionPolicy, SnapshotDifferential, } from '@zukhruf/snapshot-differential';
+import { Deduplication } from './deduplication.js';
+// Reads for a source without a change feed. An incremental copy compares one
+// complete scan with the previous snapshot, emits new or changed records, a
+// DELETE for every vanished key the policy judges deleted, then the new
+// snapshot as the only STATE. A full refresh replaces its target, so it emits
+// every record of the scan, one at a time as the scan yields it, and saves
+// nothing. rereads names the lookback window of a scan the next one repeats
+// only in part; continues makes the call one part of a scan.
+export async function* diffSnapshot({ stream, syncMode }, records, state, options) {
+    const deduplication = deduplicationOf(stream);
+    const differential = differentialOf(deduplication, options);
+    if (syncMode !== 'incremental') {
+        for await (const data of records)
+            yield { stream: stream.name, data };
+        return;
+    }
+    for await (const change of differential.diff(untilStopped(records, options.signal), state, options))
+        yield messageOf(deduplication, change);
+}
+// diffSnapshot for a scan whose records come from inputs the source can
+// fingerprint cheaply: in an incremental copy, a group whose fingerprint
+// matches the last committed scan, and a kept group, which the source knows
+// did not change, keep their records without reading them.
+export async function* diffGroupedSnapshot({ stream, syncMode }, groups, state, options) {
+    const deduplication = deduplicationOf(stream);
+    const differential = differentialOf(deduplication, options);
+    if (syncMode !== 'incremental') {
+        for await (const group of groups) {
+            // A full refresh replaces its target, so it must read every group.
+            if ('kept' in group)
+                throw new TypeError(`Stream ${stream.name} kept group ${group.key} in a full refresh, which reads every group`);
+            for await (const data of group.records())
+                yield { stream: stream.name, data };
+        }
+        return;
+    }
+    for await (const change of differential.diffGroups(untilStopped(groups, options.signal), state, options))
+        yield messageOf(deduplication, change);
+}
+// Each item of a scan until signal aborts. A scan that finds nothing changed
+// may never wait on I/O, and then no other task runs until it ends: not the
+// host's stop, its timers nor the requests it serves. So the scan gives the
+// event loop a turn every turnItems items, and once the run is cancelled it
+// ends with the signal's reason, never as a complete scan the differential
+// could delete the unread keys of.
+async function* untilStopped(items, signal) {
+    let read = 0;
+    for await (const item of items) {
+        if (++read % turnItems === 0)
+            await new Promise((resolve) => setImmediate(resolve));
+        signal?.throwIfAborted();
+        yield item;
+    }
+}
+// The most items a scan reads without letting another task run. A count, not
+// a time, so the turns do not depend on a clock: an item diffs in
+// microseconds, so a turn comes within a few milliseconds.
+const turnItems = 1000;
+// A stream that declares no emitsDeletes has an upstream that forgets
+// records rather than deleting them: every vanished key leaves the snapshot
+// without a DELETE, and its row stays loaded.
+class Forgetting extends DeletionPolicy {
+    vanished() {
+        return 'expired';
+    }
+}
+function deduplicationOf(stream) {
+    if (!stream.sourceDefinedCursor)
+        throw new TypeError(`Stream ${stream.name} must declare sourceDefinedCursor to diff snapshots`);
+    return new Deduplication(stream, stream.primaryKey);
+}
+function differentialOf(deduplication, { policy }) {
+    const { stream } = deduplication;
+    return new SnapshotDifferential({
+        name: stream.name,
+        primaryKey: stream.primaryKey,
+        key: (record) => deduplication.primaryKey.map((field) => deduplication.value(record, field)),
+        expiresBy: stream.expiresBy,
+        policy: policyOf(stream, policy),
+    });
+}
+function policyOf(stream, policy) {
+    if (!stream.emitsDeletes) {
+        if (policy !== undefined)
+            throw new TypeError(`Stream ${stream.name} emits no deletions, so its snapshot diff takes no policy`);
+        return new Forgetting();
+    }
+    if (policy === undefined)
+        throw new TypeError(stream.expiresBy === undefined
+            ? `Stream ${stream.name} emits deletions, so its snapshot diff needs a policy, such as ClosedWorld`
+            : `Stream ${stream.name} expires by ${stream.expiresBy}, so its snapshot diff needs a policy, such as Retention(horizon)`);
+    return policy;
+}
+function messageOf(deduplication, change) {
+    const { stream } = deduplication;
+    if (change.type === 'insert' || change.type === 'update')
+        return { stream: stream.name, data: change.record };
+    if (change.type === 'delete')
+        return {
+            type: 'DELETE',
+            stream: stream.name,
+            // The differential can keep bytes in a key; a stream's key fields are
+            // scalars, so the deleted key passes the same check its record did.
+            key: Object.fromEntries(deduplication.primaryKey.map((field) => [
+                field,
+                deduplication.value(change.key, field),
+            ])),
+        };
+    return { type: 'STATE', stream: stream.name, state: change.state };
+}

package/dist/core/source.d.ts

@@ -0,0 +1,79 @@
+import type { Catalog } from './catalog.ts';
+import type { ChangeSignal } from './change-signal.ts';
+import type { PipelineClock } from './clock.ts';
+import type { CopyConfiguration } from './copy-configuration.ts';
+import { type Partition } from './partition.ts';
+import type { Stream } from './stream.ts';
+import type { Upkeep } from './upkeep.ts';
+export type SourceReadOptions = {
+    readonly signal?: AbortSignal | undefined;
+    readonly clock: PipelineClock;
+};
+export type RecordMessage = {
+    readonly stream: string;
+    readonly data: unknown;
+    readonly file?: string | null;
+};
+export type StateMessage = {
+    readonly type: 'STATE';
+    readonly stream: string;
+    readonly state: unknown;
+};
+export type KeyValue = string | number | boolean;
+export type ExtractionCoverage = {
+    readonly description: string;
+    readonly selection: {
+        readonly [field: string]: JsonValue;
+    };
+};
+export type FailureType = 'config' | 'system';
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [field: string]: JsonValue;
+};
+export type DeleteMessage = {
+    readonly type: 'DELETE';
+    readonly stream: string;
+    readonly key: Readonly<Record<string, KeyValue>>;
+};
+export type ResetMessage = {
+    readonly type: 'RESET';
+    readonly stream: string;
+};
+export type ScopedReset = ResetMessage & {
+    readonly partition: Partition | null;
+};
+export type SourceMessage = RecordMessage | StateMessage | DeleteMessage | ResetMessage;
+export declare class StreamStatus {
+    readonly stream: string;
+    readonly status: 'STARTED' | 'FAILED' | 'ENDED';
+    readonly partition: Partition | null;
+    readonly error: unknown;
+    constructor(stream: string, status: 'STARTED' | 'FAILED' | 'ENDED', partition?: Partition | null, error?: unknown);
+}
+export type ReadMessage = RecordMessage | StateMessage | DeleteMessage | ScopedReset | StreamStatus;
+export declare abstract class Source<Context extends AsyncDisposable = AsyncDisposable> {
+    #private;
+    abstract readonly identity: string;
+    protected abstract readonly catalog: Catalog;
+    protected readonly concurrency: number;
+    discover(): Promise<Catalog>;
+    validate(configuration: CopyConfiguration): void;
+    protected abstract open(streams: readonly Stream[], signal: AbortSignal | undefined, states: {
+        get(stream: string): unknown;
+    }, clock: PipelineClock): Promise<Context>;
+    protected validateExtraction(_configuration: CopyConfiguration): void;
+    protected partitions(stream: Stream): readonly Partition[];
+    abstract coverage(stream: Stream): ExtractionCoverage;
+    abstract currentAsOf(stream: Stream): Promise<Date | null>;
+    protected readonly configErrors: readonly (abstract new (...args: never[]) => Error)[];
+    failureType(error: unknown): FailureType;
+    abstract changeSignals(streams: readonly Stream[], clock: PipelineClock): Iterable<ChangeSignal>;
+    upkeep(_clock: PipelineClock): Iterable<Upkeep>;
+    private member;
+    read(catalog: readonly CopyConfiguration[], states: {
+        get(stream: string): unknown;
+    }, { signal, clock }: SourceReadOptions): AsyncGenerator<ReadMessage>;
+    private resolved;
+    private partitioned;
+    protected abstract extract(configuration: CopyConfiguration, state: unknown, partition: Partition | null, context: Context, signal: AbortSignal | undefined): AsyncIterable<SourceMessage>;
+}

package/dist/core/source.js

@@ -0,0 +1,227 @@
+import { FileContent } from './file-content.js';
+import { interleave } from './interleave.js';
+import { assertInPartition, assertPartitions, partitionIdentity, readPartition, readPartitionStates, } from './partition.js';
+// Where a stream's read stands, as Airbyte's stream status: STARTED before its
+// first message; FAILED when one partition, or the whole stream when
+// partition is null, did not read; ENDED after its last message. Only
+// Source.read creates it, from what extract threw; a connector signals
+// failure by throwing.
+export class StreamStatus {
+    stream;
+    status;
+    partition;
+    error;
+    constructor(stream, status, partition = null, error = undefined) {
+        this.stream = stream;
+        this.status = status;
+        this.partition = partition;
+        this.error = error;
+        Object.freeze(this);
+    }
+}
+// Airbyte's read(config, catalog, state): one read covers every selected
+// stream, inside one context the source opens for it, so related streams see
+// the same moment of the upstream.
+export class Source {
+    // How many streams one read reads at once; their messages interleave. A
+    // source raising it reads its context from several extracts together.
+    concurrency = 1;
+    async discover() {
+        return this.catalog;
+    }
+    // Check source-owned metadata without extraction or rediscovery.
+    validate(configuration) {
+        const stream = this.member(configuration.stream);
+        configuration.validate(stream);
+        this.validateExtraction(configuration);
+        if (stream.partitionKey !== undefined)
+            assertPartitions(stream, this.partitions(stream));
+    }
+    // Source-specific selection rules, checked without I/O.
+    validateExtraction(_configuration) { }
+    // The partitions a partitioned stream is read as, asked at the start of
+    // each read and at the start of a watch, so a source whose host changes
+    // them, such as a web stream's inputs, gives the list as it is then; none
+    // is a stream that reads nothing. The list is not part of the identity:
+    // adding or removing a partition keeps every other partition's checkpoint.
+    partitions(stream) {
+        throw new TypeError(`Source must declare partitions for stream ${stream.name}`);
+    }
+    // The error classes that mean the user must act, such as an SDK's access
+    // error. Only the source knows which of its upstream's errors those are.
+    configErrors = [];
+    // What kind of failure an error from this source is: config for an instance
+    // of a class in configErrors, and system for any other error, a
+    // destination's included. A source whose decision needs more than the
+    // class, such as an HTTP status, overrides it.
+    failureType(error) {
+        return this.configErrors.some((type) => error instanceof type)
+            ? 'config'
+            : 'system';
+    }
+    // What the source keeps doing while a watch runs, such as keeping an app
+    // running when only that app syncs its store (ADR 0021). Most sources keep
+    // nothing.
+    upkeep(_clock) {
+        return [];
+    }
+    member(stream) {
+        if (this.catalog.get(stream.name) !== stream)
+            throw new TypeError(`Stream ${stream.name} is not from this source's discovered catalog`);
+        return stream;
+    }
+    // Must be lazy: the destination prepares its targets before pulling records.
+    // Each checkpoint is a commit point. A full refresh carries none, so it
+    // loads all or nothing; an incremental read that fails keeps what earlier
+    // checkpoints committed. states holds each incremental stream's saved state,
+    // or a promise of it, by stream name; a read asks for a stream's state when
+    // it starts that stream, so a state that grows with its upstream, such as a
+    // snapshot, is held only while its own stream reads. signal is the run's:
+    // each extract receives it, so one waiting on its upstream can stop once
+    // the run is cancelled. Streams that read together are one task group, as
+    // Python's asyncio.TaskGroup: the first one that throws aborts the signal
+    // the others read with, so a stream that waits on another, such as a
+    // consumer of a sibling's outbox, ends with the read.
+    async *read(catalog, states, { signal, clock }) {
+        for (const configuration of catalog)
+            this.validate(configuration);
+        if (new Set(catalog.map(({ stream }) => stream.name)).size !== catalog.length)
+            throw new TypeError('A read selects each stream once');
+        const group = new AbortController();
+        const reading = signal === undefined
+            ? group.signal
+            : AbortSignal.any([signal, group.signal]);
+        await using context = await this.open(catalog.map(({ stream }) => stream), reading, states, clock);
+        if (!Number.isSafeInteger(this.concurrency) || this.concurrency < 1)
+            throw new TypeError('Source concurrency must be a positive integer');
+        yield* interleave(catalog.map((configuration) => grouped(this.#stream(configuration, states, context, reading), group)), this.concurrency);
+    }
+    async *#stream(configuration, states, context, signal) {
+        const { name } = configuration.stream;
+        yield new StreamStatus(name, 'STARTED');
+        const state = (await states.get(name)) ?? null;
+        if (configuration.stream.partitionKey !== undefined)
+            yield* this.partitioned(configuration, state, context, signal);
+        else {
+            const incremental = configuration.syncMode === 'incremental';
+            try {
+                for await (const message of this.resolved(configuration, this.extract(configuration, state, null, context, signal), signal))
+                    if (!('type' in message) || message.type === 'DELETE')
+                        yield message;
+                    else if (incremental)
+                        yield message.type === 'RESET'
+                            ? { ...message, partition: null }
+                            : message;
+            }
+            catch (error) {
+                yield new StreamStatus(name, 'FAILED', null, error);
+            }
+        }
+        yield new StreamStatus(name, 'ENDED');
+    }
+    // Keeps each message to the stream whose extract emitted it, and replaces
+    // each record's file path with the file reads it asked for.
+    async *resolved(configuration, messages, signal) {
+        for await (const message of messages) {
+            if (message instanceof StreamStatus)
+                throw new TypeError('Only Source.read reports stream status; extract signals failure by throwing');
+            if (message.stream !== configuration.stream.name)
+                throw new TypeError(`Extract for ${configuration.stream.name} emitted ${message.stream}`);
+            if ('type' in message &&
+                message.type === 'RESET' &&
+                Object.hasOwn(message, 'partition'))
+                throw new TypeError('Only Source.read scopes a reset to its partition');
+            if ('type' in message || configuration.fileReads.length === 0) {
+                yield message;
+                continue;
+            }
+            if (message.file !== null && typeof message.file !== 'string')
+                throw new TypeError('File extraction must supply a file path or explicit null');
+            const data = message.data;
+            if (data === null || typeof data !== 'object' || Array.isArray(data))
+                throw new TypeError('File metadata must be an object');
+            const output = { ...data };
+            const values = new Map();
+            for (const read of configuration.fileReads) {
+                if (Object.keys(data).some((name) => name.toLowerCase() === read.name.toLowerCase()))
+                    throw new TypeError('File field collides with source metadata');
+                let value = null;
+                if (message.file !== null) {
+                    let pending = values.get(read.parser);
+                    if (pending === undefined) {
+                        pending =
+                            read.parser === undefined
+                                ? new FileContent(message.file)
+                                : read.parser.parse(message.file, signal);
+                        values.set(read.parser, pending);
+                    }
+                    value = await pending;
+                    if (read.parser !== undefined &&
+                        value !== null &&
+                        typeof value !== 'string')
+                        throw new TypeError('Document parser must return text or null');
+                }
+                Object.defineProperty(output, read.name, { value, enumerable: true });
+            }
+            yield { stream: message.stream, data: output };
+        }
+    }
+    // Reads each partition with its own saved state: null for a partition not
+    // seen before, so it starts from the source's normal beginning. Every
+    // checkpoint carries all listed partitions' latest states, so a partition
+    // not yet read, or one that failed, keeps what it had. Partitions no longer
+    // listed drop out of the next checkpoint; their rows stay loaded.
+    async *partitioned(configuration, state, context, signal) {
+        const { stream } = configuration;
+        const incremental = configuration.syncMode === 'incremental';
+        const saved = incremental
+            ? readPartitionStates(stream, state)
+            : new Map();
+        const identity = partitionIdentity(stream);
+        const listed = this.partitions(stream).map((entry) => readPartition(identity, entry));
+        const latest = new Map(saved);
+        for (const { key, partition } of listed) {
+            try {
+                for await (const message of this.resolved(configuration, this.extract(configuration, saved.get(key)?.state ?? null, partition, context, signal), signal)) {
+                    if ('type' in message && message.type === 'STATE') {
+                        if (!incremental)
+                            continue;
+                        latest.set(key, { partition, state: message.state });
+                        yield {
+                            type: 'STATE',
+                            stream: stream.name,
+                            state: {
+                                partitions: listed.flatMap((entry) => latest.get(entry.key) ?? []),
+                            },
+                        };
+                        continue;
+                    }
+                    if ('type' in message && message.type === 'RESET') {
+                        if (incremental)
+                            yield { ...message, partition };
+                        continue;
+                    }
+                    assertInPartition(stream, partition, 'type' in message ? message.key : message.data);
+                    yield message;
+                }
+            }
+            catch (error) {
+                yield new StreamStatus(stream.name, 'FAILED', partition, error);
+                // A full refresh commits nothing after a failure; stop reading.
+                if (!incremental)
+                    return;
+            }
+        }
+    }
+}
+// A stream that throws aborts its group before the throw reaches interleave,
+// which waits for every other stream to settle.
+async function* grouped(messages, group) {
+    try {
+        yield* messages;
+    }
+    catch (error) {
+        group.abort(error);
+        throw error;
+    }
+}

package/dist/core/stream-change.d.ts

@@ -0,0 +1,5 @@
+export declare class StreamChangeError extends TypeError {
+    name: string;
+    constructor(id: string, changed: readonly string[]);
+}
+export declare function changedDeclarations(saved: unknown, current: unknown): string[];

package/dist/core/stream-change.js

@@ -0,0 +1,31 @@
+import { isDeepStrictEqual } from 'node:util';
+// The declarations that say how a stream's records are identified, read and
+// deleted. Changing one changes what the stored rows mean, so their copy
+// cannot carry on from its checkpoint. Airbyte pauses a connection on the
+// same kind of change, a removed primary key or cursor, and asks the user to
+// refresh or clear.
+const declarations = [
+    'name',
+    'primaryKey',
+    'partitionKey',
+    'supportedSyncModes',
+    'supportsFileTransfer',
+    'sourceDefinedCursor',
+    'emitsDeletes',
+    'expiresBy',
+];
+// A copy's stream changed one of its declarations since its checkpoint was
+// saved. The host decides what happens to the stored rows: a reset keeps them
+// and loads on from no checkpoint, a clear drops them.
+export class StreamChangeError extends TypeError {
+    name = 'StreamChangeError';
+    constructor(id, changed) {
+        super(`Stream of copy ${id} changed its ${changed.join(', ')}; reset the copy to keep its rows, or clear it to drop them`);
+    }
+}
+// The declarations a stream changed between two of its shapes, as a
+// checkpoint binding keeps them. Any other change, to its fields and their
+// types, is one the destination evolves its target to.
+export function changedDeclarations(saved, current) {
+    return declarations.filter((declaration) => !isDeepStrictEqual(Reflect.get(Object(saved), declaration), Reflect.get(Object(current), declaration)));
+}

package/dist/core/stream.d.ts

@@ -0,0 +1,26 @@
+import { FileReference } from './file-read.ts';
+import type { StreamSchema } from './record-validation.ts';
+export type SyncMode = 'full_refresh' | 'incremental';
+export declare class Stream {
+    readonly name: string;
+    readonly jsonSchema: StreamSchema;
+    readonly primaryKey: readonly string[];
+    readonly supportedSyncModes: readonly SyncMode[];
+    readonly supportsFileTransfer?: true;
+    readonly sourceDefinedCursor?: true;
+    readonly emitsDeletes?: true;
+    readonly partitionKey?: readonly string[];
+    readonly expiresBy?: string;
+    constructor({ name, jsonSchema, primaryKey, supportedSyncModes, supportsFileTransfer, sourceDefinedCursor, emitsDeletes, partitionKey, expiresBy, }: {
+        name: string;
+        jsonSchema: StreamSchema;
+        primaryKey?: readonly string[];
+        supportedSyncModes: readonly SyncMode[];
+        supportsFileTransfer?: true;
+        sourceDefinedCursor?: true;
+        emitsDeletes?: true;
+        partitionKey?: readonly string[];
+        expiresBy?: string;
+    });
+    get file(): FileReference;
+}