@smart-data-engines/sde 0.1.0-dev.0

package/dist/session.d.ts

@@ -0,0 +1,195 @@
+import type { Group } from './groups.js';
+import type { NameMap } from './hashing.js';
+import type { LogicalModel } from './model.js';
+import type { NumericSummary, ReadOptions, ScanPage } from './query.js';
+import type { PhysicalLayout, PlacementMap } from './placement.js';
+import type { Recorder, StorageMeasurement } from './telemetry.js';
+import type { WatermarkCheck } from './watermark.js';
+import type { PhysicalFinding } from './physical.js';
+export type Row = Record<string, unknown>;
+/** What an adapter has to offer for a session to route to it. */
+export interface Engine {
+    readonly dialect: string;
+    /**
+     * Create what is missing and return how existing tables differ from the declared physical
+     * design. `void` remains acceptable from an adapter written before findings existed.
+     */
+    ensureSchema(layout: PhysicalLayout, options: {
+        readonly keys: Readonly<Record<string, readonly string[]>>;
+    }): Promise<readonly PhysicalFinding[] | void>;
+    insert(table: string, values: Readonly<Row>): Promise<void>;
+    get(table: string, key: Readonly<Row>): Promise<Row | null>;
+    /**
+     * One engine, one transaction, that engine's semantics.
+     *
+     * A callback rather than a pair of begin/commit calls, so a caller cannot leave one open. There
+     * is no distributed transaction here and there will not be one: a client needing two entities to
+     * commit together declares that, the planner puts them in the same group and therefore the same
+     * engine, and the requirement turns into a placement constraint instead of a two-phase commit.
+     */
+    transaction<T>(body: () => Promise<T>): Promise<T>;
+}
+export type ScanOptions = Omit<ReadOptions, 'paginate'> & {
+    readonly fresh?: boolean;
+};
+export type CountOptions = Pick<ScanOptions, 'where' | 'bounds' | 'fresh'>;
+export type SummaryOptions = CountOptions & {
+    readonly meanScale?: number;
+};
+export interface SessionOptions {
+    readonly projectId?: string;
+    /**
+     * Telemetry is optional and off by default. A library that starts measuring the moment it is
+     * imported is a library people are right to be suspicious of; measurement begins when a recorder
+     * is handed in, which is a visible line in the client's code.
+     */
+    readonly recorder?: Recorder;
+    /** The name map from {@link hashIdentifiers}, when the client hashes their identifiers. */
+    readonly names?: NameMap;
+}
+export interface ManagedEngine extends Engine {
+    connect(): Promise<void>;
+    close(): Promise<void> | void;
+}
+export declare class Session {
+    readonly model: LogicalModel;
+    readonly placement: PlacementMap;
+    private readonly engines;
+    private readonly recorder;
+    private readonly names;
+    /**
+     * Whether an older map could be loaded over this one, and why.
+     *
+     * Public because a protection whose state cannot be read is a protection taken on trust. It has
+     * three values and the middle one matters: `enforced`, `unavailable` - no engine in this map can
+     * keep the bookkeeping - and `not_applicable` for an unsigned map, which is the client's own
+     * document.
+     */
+    readonly rollbackProtection: WatermarkCheck;
+    readonly projectId: string | undefined;
+    private readonly shapes;
+    private readonly inputFields;
+    private readonly groups;
+    private readonly reverseFields;
+    private readonly declared;
+    private inWriteTransaction;
+    private deferred;
+    private readonly usage;
+    private ownedEngines;
+    private closing;
+    private physicalFindings;
+    private constructor();
+    /**
+     * Open a session, refusing a map this set of engines cannot serve and one that goes backwards.
+     *
+     * Both checks are here rather than in a method somebody has to remember to call, and here rather
+     * than in `ensureSchema`, which a deployment past its first release skips. A rolled-back map file
+     * is read at process start, so the check has to be on the path every start takes.
+     */
+    static open(model: LogicalModel, placement: PlacementMap, engines: Readonly<Record<string, Engine>>, options?: SessionOptions): Promise<Session>;
+    /** Create and own fresh adapters, including cleanup when only part of startup succeeded. */
+    static connect(model: LogicalModel, placement: PlacementMap, factories: Readonly<Record<string, () => ManagedEngine | Promise<ManagedEngine>>>, options?: SessionOptions): Promise<Session>;
+    /** Close only adapters created by Session.connect; borrowed adapters remain the caller's. */
+    close(): Promise<void>;
+    /** The client's entity name, as the model knows it. */
+    private entityName;
+    private fieldsIn;
+    private fieldsOut;
+    private clientNames;
+    /**
+     * The adapter registered under this name, refusing an unknown one.
+     *
+     * Exposed for the migration module, which needs all three of what a session holds and is
+     * deliberately a set of free functions rather than methods here: a call that copies a table for
+     * an hour has no business sitting in autocomplete next to `save`. Reaching into a private field
+     * from a sibling module would have worked and would have made this class a friend of that one,
+     * which is a worse arrangement than admitting what a session holds.
+     */
+    engineNamed(name: string): Engine;
+    /** The adapters, by the names the map uses. A copy; the session keeps its own. */
+    engineNames(): readonly string[];
+    groupOf(entity: string): Group;
+    private shapeFor;
+    private target;
+    /**
+     * How existing tables differ from the physical design the map declares, if at all.
+     *
+     * Reported, never refused, because the difference is performance: a table whose sort key,
+     * partition or index is not the declared one still stores and returns exactly the same rows, and
+     * turning that into an outage would make this library the thing that broke production
+     * (requirement 3.6). `prepareSchema` refuses the same differences, which is where a person can
+     * act on them. This runtime has no log channel, so the property is the whole report.
+     */
+    get physical(): readonly PhysicalFinding[];
+    /** Create what each engine is missing for the groups placed in it. */
+    ensureSchema(): Promise<void>;
+    /** Whether an engine in this map imposes its own schema, so `ensureSchema` sends it nothing. */
+    fixedSchemaEngines(): readonly string[];
+    save(entity: string, values: Readonly<Row>): Promise<void>;
+    /**
+     * Measure each group's size on its source materialisation, from the engine's catalogue.
+     *
+     * One catalogue statement per engine, for every table of every group whose source is on it. Only
+     * the source counts: a copy a staging is still building is not the group's size. Each size is
+     * recorded into this session's recorder, when it has one, for the window's `total_bytes`,
+     * `index_to_table_ratio` and `daily_growth_bytes`.
+     *
+     * **It never throws because an engine could not answer.** An adapter with no catalogue, a refused
+     * read, a failed one or a table the map names that does not exist leaves that group's size
+     * unknown, with the class of the reason in `unavailable`. Using a closed session, or an adapter
+     * another operation owns, still throws, as every method of a session does.
+     */
+    measureStorage(): Promise<StorageMeasurement>;
+    /** One bounded native insert. No splitting or retry; see docs/bulk-writes.md. */
+    saveMany(entity: string, rows: readonly Readonly<Row>[]): Promise<void>;
+    get(entity: string, key: Readonly<Row>, options?: {
+        fresh?: boolean;
+    }): Promise<Row | null>;
+    /**
+     * Write the row to every `also_write` copy of the group. Additionally, never authoritatively.
+     *
+     * **A failure here does not interrupt the client's operation.** The row is in the source, which is
+     * the copy that counts, and turning a migration into an application outage would make the safest
+     * thing this product does the most dangerous. So the divergence is recorded and `verify` is the
+     * gate that refuses to switch reads while any of them remain.
+     *
+     * Inside a write transaction the fan-out is **deferred to commit** rather than skipped or done
+     * inline, and each of those three was considered. Inline is wrong: the target is a different
+     * engine, so it is outside the source's transaction, and a rolled-back row would exist in the
+     * copy - which after the switch is a row the client explicitly undid, readable. Skipping is wrong
+     * for a quieter reason: those rows are above the backfill marker, so nothing else copies them,
+     * and `verify`'s tail check would refuse the migration of every group that uses a transaction.
+     */
+    private fanOut;
+    /**
+     * Write one row to one copy, measure how long the copy was behind, and never throw.
+     *
+     * `queuedNs` is when the row was handed to the fan-out, so the interval measured is the whole
+     * time the copy did not have a row the source did. Outside a transaction that is the duration of
+     * this write; inside one it also includes the rest of the transaction, which **overstates** the
+     * staleness - the safe direction for a bound somebody checks a budget against.
+     */
+    private replayOne;
+    private prepareRead;
+    private readProjection;
+    /** One bounded page in logical order, independently of migration checkpoints. */
+    scan(entity: string, options?: ScanOptions): Promise<ScanPage>;
+    /** An exact count; the result value itself is never telemetry. */
+    count(entity: string, options?: CountOptions): Promise<bigint>;
+    summarize(entity: string, field: string, options?: SummaryOptions): Promise<NumericSummary>;
+    private observe;
+    /**
+     * Run `body` inside a transaction covering the given entities.
+     *
+     * They must share a colocation group, because a transaction is one engine's transaction. If they
+     * do not, this throws before anything is opened and names the fix: declare the atomicity, and the
+     * planner will colocate them.
+     *
+     * Called with no entities it covers the whole model, which is only legal when the model has one
+     * group. That is not a convenience for small models so much as a refusal to let a two-group model
+     * quietly get a transaction that only covers half of what the caller meant.
+     */
+    transaction<T>(entities: readonly string[], body: (session: Session) => Promise<T>): Promise<T>;
+}
+/** The table this layout gives an entity, refusing a map that places a group it cannot name. */
+export declare function tableFor(layout: PhysicalLayout, entity: string): string;