@routier/core 0.4.0 → 0.6.0

package/dist/plugins/resultShape.d.ts

@@ -0,0 +1,35 @@
+import type { PropertyInfo } from '../schema/PropertyInfo';
+import type { QueryField } from './query/types';
+/**
+ * What a statement or command RETURNS, described before it runs.
+ *
+ * A plugin's builder knows this and nothing else knows it: the shape of a result comes from the
+ * projection, the join aliases, or the `RETURNING` list, none of which survive into the SQL as
+ * anything a reader could recover. So the builder states it, once, beside the statement it built.
+ *
+ * Deliberately says nothing about what anyone does with the result. It is a description, not an
+ * instruction — the same description serves a driver that transfers rows across a worker
+ * boundary, one that hands them straight back, and one that only wants to know the column order.
+ * A consumer that needs more turns this into whatever it needs: `buildTransferPlan` in
+ * `@routier/core/transfer` is one such consumer, and it is not privileged.
+ */
+export type ResultColumn = {
+    /** Exact name the engine will return, including any projection or join alias. */
+    readonly name: string;
+    /**
+     * The schema property behind the column, or `null`.
+     *
+     * `null` for an expression — a computed value, an aggregate, anything with no declared type
+     * to reason from. A consumer that wants to treat the value specially needs the property; one
+     * that only wants names does not.
+     */
+    readonly property: PropertyInfo<any> | null;
+};
+/**
+ * The columns a `map` projection selects.
+ *
+ * Named by `sourceName`, which is what the statement actually emits; the rename to
+ * `destinationName` happens in the translator, after the rows come back. A field with no
+ * `property` is an expression.
+ */
+export declare const mappedResultColumns: (fields: readonly QueryField[]) => ResultColumn[];

package/dist/transfer/ChunkEncoder.d.ts

@@ -0,0 +1,60 @@
+import { EncodedTransfer, TransferPlan } from './types';
+/**
+ * Fills one chunk at a time from row values, and emits it with the buffers its transport can hand
+ * over.
+ *
+ * One encoder per result, not per chunk: a column that falls back to `clone` stays there for
+ * every later chunk, and a forward-only cursor cannot rewind to re-encode what it already yielded.
+ *
+ * Usage is a loop — `appendRow` or `appendRecord` until `isFull`, `take`, repeat, then `take` once
+ * more for the short final chunk. A zero-row result takes exactly one chunk with `rowCount: 0`.
+ */
+export declare class ChunkEncoder {
+    private readonly columns;
+    private readonly fillers;
+    private readonly inheritedNames;
+    private rows;
+    constructor(plan: TransferPlan);
+    /** Rows in the chunk being filled. */
+    get rowCount(): number;
+    get isFull(): boolean;
+    /** The column names, in the order a row's values must arrive in. */
+    get columnNames(): readonly string[];
+    /**
+     * Adds one row, its values in plan column order.
+     *
+     * A value that does not belong in its column's encoding sends that column to `clone` for the
+     * rest of the result, carrying the rows already written with it. Nothing is coerced into a
+     * typed array.
+     */
+    appendRow(values: readonly unknown[]): void;
+    /**
+     * Adds one row from a NAME-KEYED record, reading each planned column out of it.
+     *
+     * For an engine that yields records rather than positional tuples — a document store, a
+     * key-value store, a driver that returns row objects. Projecting to an array is the caller's
+     * alternative, and getting that order wrong is silent corruption rather than an error, so the
+     * mapping belongs here once instead of in every plugin.
+     *
+     * A column the record does not carry is `null`, not an error. Records are legitimately
+     * heterogeneous outside a fixed-schema table, and the plan is what decides the result shape.
+     */
+    appendRecord(record: Record<string, unknown>): void;
+    /**
+     * A plain read, unless a planned name is one the prototype chain answers for.
+     *
+     * `record['__proto__']` on an object literal returns `Object.prototype` rather than
+     * `undefined`, and `toString` returns a function — either would be encoded as a value. The
+     * own-property test that avoids it costs a call per field, so it is only taken when a name in
+     * this plan actually needs it.
+     */
+    private readField;
+    /**
+     * Emits the filled chunk and readies the encoder for the next one.
+     *
+     * Transfer DETACHES the emitted buffers, so the fillers allocate fresh arrays here rather
+     * than reusing them. Reading a chunk's typed arrays after this is a use-after-transfer.
+     */
+    take(): EncodedTransfer;
+    private fallBack;
+}

package/dist/transfer/decoder.d.ts

@@ -0,0 +1,29 @@
+import { EncodedChunk, TransferPlan } from './types';
+/**
+ * A chunk's JSON document did not parse.
+ *
+ * Reported as its own shape so a caller can retry the request WITHOUT a plan and get today's
+ * clone path, which parses row by row and tolerates a field holding text that is not JSON.
+ * Every other decode failure is a real error.
+ *
+ * Read structurally rather than with `instanceof`: an error constructed in another realm — Jest
+ * gives each test file its own — fails the prototype test for exactly the cases this classifies.
+ */
+export type TransferJsonError = Error & {
+    readonly transferJsonColumn: string;
+};
+export declare const isTransferJsonError: (error: unknown) => error is TransferJsonError;
+/** Emptied between tests. Not part of the decoding contract. */
+export declare const clearDecoderCache: () => void;
+export declare const isTransferCodecSupported: () => boolean;
+/**
+ * Decodes one chunk into final-shape row objects — real booleans, `Date` objects, parsed JSON.
+ *
+ * Not the raw storage shape. The entity needs the final shape either way, and decoding to raw and
+ * re-shaping afterwards measured slower (156ms against 140ms at 100,000 rows). An absent or null
+ * value becomes JavaScript `null`, never `undefined` and never an absent property.
+ *
+ * A column that fell back to `clone` in the worker comes back RAW, and the caller still owes it
+ * whatever shaping that column would otherwise have had.
+ */
+export declare const decodeChunk: (plan: TransferPlan, chunk: EncodedChunk) => unknown[];

package/dist/transfer/fillers.d.ts

@@ -0,0 +1,36 @@
+import { EncodedColumn, TransferEncoding } from './types';
+/**
+ * One column being filled, one strategy per encoding.
+ *
+ * `set` answers `false` rather than coercing a value that does not belong in its encoding. A
+ * schema type does not prove what an engine will actually return — custom serializers,
+ * migrations and external writers can put anything in a field — so the encoder validates every
+ * value it writes instead of trusting the plan. The caller turns a refusal into a fallback to
+ * `clone`.
+ */
+export interface ColumnFiller {
+    readonly encoding: TransferEncoding;
+    set(index: number, value: unknown): boolean;
+    /** Rows `0..count` as raw values, which is what a fallback to `clone` has to carry forward. */
+    drain(count: number): unknown[];
+    emit(rowCount: number, transferables: ArrayBufferLike[]): EncodedColumn;
+    /** Readies the filler for the next chunk. Transfer detaches the buffers, so they are replaced. */
+    reset(): void;
+}
+/**
+ * Raw values in a plain array, structured-cloned as they are.
+ *
+ * Strings live here and are never encoded. `TextEncoder` loses to clone by a wide margin —
+ * 14.0ms against 8.3ms for 4,000 rows of 2KB text — because cloning a V8 string is a native
+ * memcpy.
+ */
+export declare class CloneFiller implements ColumnFiller {
+    readonly encoding: "clone";
+    private data;
+    constructor(seed?: unknown[]);
+    set(index: number, value: unknown): boolean;
+    drain(count: number): unknown[];
+    emit(rowCount: number): EncodedColumn;
+    reset(): void;
+}
+export declare const createFiller: (encoding: TransferEncoding) => ColumnFiller;