@clickhouse/client 1.23.0-head.dbc2960.1 → 1.23.0

package/skills/clickhouse-js-node-rowbinary/src/writers/writer.ts

@@ -0,0 +1,101 @@
+/**
+ * Barrel re-export of the RowBinary WRITER — the encode mirror of `reader.ts`,
+ * split by type family across parallel `*.ts` modules (the readers stay in
+ * their own files untouched). Import from here for everything in one place, or
+ * from a specific module (e.g. `./integers.js`, `./strings.js`) to
+ * pull in only the sub-writers a given result needs — the latter is what a
+ * generated encoder should do, copying just the modules its column types require.
+ *
+ * Each `writeX` is the inverse of the matching `readX`: it appends the value's
+ * RowBinary bytes to a {@link Sink} (the write-side mirror of the reader's
+ * `Cursor`). Leaf writers are `Writer<T>`s directly; combinators (e.g.
+ * `writeArray`) take sub-writers and return a `Writer`, so types compose with no
+ * per-element closures — exactly like the reader combinators.
+ *
+ *   const sink = new Sink(Buffer.allocUnsafe(64));
+ *   writeUInt8(sink, 255);
+ *   sink.bytes(); // the encoded RowBinary
+ *
+ * - core — Sink, Writer<T>, reserve (mirror of Cursor, Reader<T>, advance)
+ * - varint — writeUVarint
+ *
+ * The dynamic AST-based encode path (the inverse of `compile.ts` /
+ * `rowBinaryWithNamesAndTypes.ts` / `dynamic.ts`) is intentionally NOT part of
+ * this barrel yet.
+ */
+export { Sink, reserve, BufferFull, type Writer } from "./core.js";
+export { writeUVarint } from "./varint.js";
+export {
+  writeUInt8,
+  writeInt8,
+  writeUInt16,
+  writeInt16,
+  writeUInt32,
+  writeInt32,
+  writeUInt64,
+  writeInt64,
+  writeUInt128,
+  writeInt128,
+  writeUInt256,
+  writeInt256,
+} from "./integers.js";
+export { writeBool } from "./bool.js";
+export { writeEnum8, writeEnum16 } from "./enums.js";
+export { writeFloat32, writeFloat64, writeBFloat16 } from "./floats.js";
+export {
+  writeDecimal32,
+  writeDecimal64,
+  writeDecimal128,
+  writeDecimal256,
+  parseDecimal,
+} from "./decimals.js";
+export {
+  writeString,
+  writeStringBytes,
+  writeFixedString,
+  writeFixedStringBytes,
+} from "./strings.js";
+export {
+  writeUUID,
+  writeUUIDBigInt,
+  writeUUIDHiLo,
+  parseUUID,
+} from "./uuid.js";
+export { writeIPv4, writeIPv6, parseIPv4, parseIPv6 } from "./ip.js";
+export {
+  writeDate,
+  writeDate32,
+  writeDateTime,
+  writeDateTime64,
+  writeDateTime64P3,
+  writeDateTime64P6,
+  writeDateTime64P9,
+} from "./datetime.js";
+export { writeTime, writeTime64, parseTime, parseTime64 } from "./time.js";
+export { writeInterval } from "./interval.js";
+export {
+  writeNullable,
+  writeArray,
+  writeQBit,
+  writeTuple,
+  writeTupleNamed,
+  writeMap,
+  writeVariant,
+  type VariantValue,
+} from "./composite.js";
+export { writeRows, FLUSH_CHANNEL_NAME, type WriteRowsFlush } from "./rows.js";
+export {
+  writePoint,
+  writeRing,
+  writeLineString,
+  writePolygon,
+  writeMultiLineString,
+  writeMultiPolygon,
+  writeGeometry,
+  type GeometryValue,
+} from "./geo.js";
+export { writeLowCardinality } from "./lowCardinality.js";
+export { writeSimpleAggregateFunction } from "./simpleAggregateFunction.js";
+export { writeNested } from "./nested.js";
+export { writeNothing } from "./nothing.js";
+export { writeAggregateFunction } from "./aggregateFunction.js";

package/skills/clickhouse-js-node-rowbinary/writer.md

@@ -0,0 +1,96 @@
+# RowBinary writer (encode) for Node.js
+
+Encoding JS values into a `RowBinary` payload to send to ClickHouse. Read
+[SKILL.md](SKILL.md) first for the format gate ("is RowBinary even the right
+format?") and the principles that apply to **both** directions; this file covers
+what's specific to **writing**. Reading? See [reader.md](reader.md).
+
+Each `writeX` encodes one value, appending its RowBinary bytes to a `Sink` (a
+caller-supplied byte buffer plus the current write offset — state only, no write
+methods). Leaf writers (`writeUInt8`, `writeString`, …) encode directly;
+combinators (`writeArray`, `writeTuple`, …) take sub-writers and return a writer,
+so composite types compose with no per-element closures. For the `Sink`/`Writer<T>`
+types and how to drain the encoded bytes, see `src/writers/core.ts`. Import the
+barrel as `@clickhouse/rowbinary/writer`, or a per-type module for just what you
+need. (Structurally this is the mirror of the decode side in
+[reader.md](reader.md), but you don't need the read side to write.)
+
+## Writer guidance
+
+On top of the shared principles in [SKILL.md](SKILL.md), the write path has its own:
+
+- **Reserve before you write.** Every fixed-width write goes through `reserve()`,
+  which bounds-checks against the fixed-length buffer and throws the `BufferFull`
+  sentinel when the chunk is full — your cue to flush what's written and continue
+  into a fresh buffer. Exact signature, return value, and throw contract are in
+  `src/writers/core.ts`.
+
+- **Coalesce `reserve()` across a run of adjacent fixed-width columns.** Their
+  combined size is statically known, so reserve ONCE for the whole run and write
+  each value at a constant offset off the returned base — one bounds-check instead
+  of one per column. Only applies where every column in the run is fixed-width (a
+  variable-width writer like `writeString` reserves on its own).
+
+- **Hoist sink state into locals in the generated writer.** `Sink.buf`/`Sink.view`
+  are `readonly`, so bind them to locals once at the top and address them directly
+  instead of through `sink.` on every write. Keep the write position (`sink.pos`)
+  in a local too — but sync it back to `sink.pos` before any `reserve()` or
+  `BufferFull` throw, since those read and mutate it to decide capacity and where a
+  flushed buffer resumes.
+
+- **Stream the whole result with `writeRows`, not a one-shot writer.** When you
+  need to encode a large or unbounded row source, reach for `writeRows` rather than
+  a `Writer<readonly T[]>`: it owns a fixed buffer and yields it as a generator,
+  streaming the result out chunk by chunk instead of demanding it all fit at once.
+  It never leaks a half-written row (it rewinds to the last whole-row boundary
+  before flushing) and never fails on a single big row (it grows the buffer to fit).
+  It also publishes a per-flush diagnostics-channel event for buffer-utilization
+  metrics. Signature, default buffer size, channel name and payload type, the
+  growth/rewind details, and a usage example are all in `src/writers/rows.ts`.
+
+- **No defensive validation on the hot path.** Don't add `isFinite`/`NaN`/range
+  checks to `writeX`; document the precondition in JSDoc instead. Two narrow
+  exceptions — framing-keeping checks and zero-cost parse-time helpers — are
+  spelled out in [AGENTS.md](AGENTS.md); `src/writers/ip.ts` is the worked
+  example (`writeIPv6`, `parseIPv6`).
+
+- **Lossy time conversions floor, never round.** Every date/time writer in
+  `src/writers/datetime.ts` drops the sub-unit it can't encode by flooring toward
+  −∞, so a caller's value is never silently shifted _up_ to the wrong
+  day/second/tick and pre-1970 instants stay correct (not rounded toward the
+  epoch). See its JSDoc for the per-function specifics.
+
+## Writer type family references
+
+The writers live as real code under `src/writers/`, one file per type family
+(same basenames as the readers, under the `writers/` directory).
+
+| Value to encode (trigger)                                                               | Open                                     |
+| --------------------------------------------------------------------------------------- | ---------------------------------------- |
+| **Always** — sink state, `reserve()`, `BufferFull`, `Writer<T>`                         | `src/writers/core.ts`                    |
+| LEB128 length/count prefixes for `String`/`Array`/`Map` (`writeUVarint`)                | `src/writers/varint.ts`                  |
+| `Int8`–`Int256`, `UInt8`–`UInt256`                                                      | `src/writers/integers.ts`                |
+| `Bool` (`writeBool`)                                                                    | `src/writers/bool.ts`                    |
+| `Enum8`, `Enum16` (`writeEnum8`/`writeEnum16`; pass the raw int)                        | `src/writers/enums.ts`                   |
+| `Float32`, `Float64`, `BFloat16`                                                        | `src/writers/floats.ts`                  |
+| `Decimal32/64/128/256`, `Decimal(P, S)` (`parseDecimal`)                                | `src/writers/decimals.ts`                |
+| `String`, `FixedString(N)` (`writeString`/`writeStringBytes`/`writeFixedString`)        | `src/writers/strings.ts`                 |
+| `UUID` (`writeUUID`, `parseUUID`)                                                       | `src/writers/uuid.ts`                    |
+| `IPv4`, `IPv6` (`writeIPv4`/`writeIPv6`, `parseIPv4`/`parseIPv6`)                       | `src/writers/ip.ts`                      |
+| `Date`, `Date32`, `DateTime`, `DateTime(tz)`, `DateTime64(P[, tz])`                     | `src/writers/datetime.ts`                |
+| `Time`, `Time64(P)` (`parseTime`/`parseTime64`)                                         | `src/writers/time.ts`                    |
+| `IntervalNanosecond` … `IntervalYear`                                                   | `src/writers/interval.ts`                |
+| `Array(T)`, `Map(K, V)`, `Tuple(...)`, `Nullable(T)`, `Variant(...)`, `QBit(...)`       | `src/writers/composite.ts`               |
+| `Point`, `Ring`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`, `Geometry` | `src/writers/geo.ts`                     |
+| The whole result — write rows from a value source (`writeRows`)                         | `src/writers/rows.ts`                    |
+| `LowCardinality(T)` — transparent, encode as `T`                                        | `src/writers/lowCardinality.ts`          |
+| `SimpleAggregateFunction(f, T)` — transparent, encode as `T`                            | `src/writers/simpleAggregateFunction.ts` |
+| `Nested(...)` — no wire of its own; `Array(Tuple(...))`                                 | `src/writers/nested.ts`                  |
+| `Nothing` — zero-width, never encoded (only wrapped)                                    | `src/writers/nothing.ts`                 |
+| `AggregateFunction(...)` — opaque state; produce server-side                            | `src/writers/aggregateFunction.ts`       |
+
+**No writer counterpart yet** — these reader paths are decode-only for now:
+`dynamic.ts`, `json.ts`, `stream.ts`, the `RowBinaryWithNamesAndTypes`
+header/compile/runtime path (`header.ts`, `compile.ts`,
+`rowBinaryWithNamesAndTypes.ts`), and the columnar typed-array path
+(`columnar.ts`). The AST-based dynamic encode path is intentionally not built.

package/skills/clickhouse-js-node-rowbinary-parser/src/enums.ts

@@ -1,28 +0,0 @@
-import { Cursor, advance } from "./core.js";
-
-/**
- * Read an `Enum8`: the value's underlying signed `Int8`. The name<->value map
- * lives in the column's type, not the bytes. Two strategies, both better than one
- * shared name-resolving reader:
- *
- * - Keep the number: carry the raw Int8 and map to a name only where needed —
- *   most hot loops never need it.
- * - Or generate a per-enum reader with a baked-in constant map, so the JIT can
- *   monomorphize each enum's decode:
- *
- *     const STATUS = { 1: "active", 2: "closed" } as const;
- *     const readStatusEnum = (s) => STATUS[readInt8(s) as keyof typeof STATUS];
- */
-export function readEnum8(state: Cursor): number {
-  return state.view.getInt8(advance(state, 1));
-}
-
-/**
- * Read an `Enum16`: the value's underlying signed `Int16` (2 bytes). The
- * name<->value map lives in the column's type definition, not the bytes. Prefer
- * keeping the number, or a generated per-enum reader with a baked-in constant
- * map so the JIT can optimize each enum's decode independently.
- */
-export function readEnum16(state: Cursor): number {
-  return state.view.getInt16(advance(state, 2), true);
-}