binding.d.cts

/* auto-generated by NAPI-RS */
/* eslint-disable */

/**
 * `Temporal.PlainDate`, on a program that has it.
 *
 * Asked of `globalThis` rather than imported, because `Temporal`
 * reached Stage 4 in March 2026 and which `lib` declares it is
 * different in every version of TypeScript that has shipped since. A
 * program compiling against a `lib` that has `Temporal` gets the real
 * type here and is checked against it. One compiling against a `lib`
 * that does not gets `unknown`, which needs a cast at the call site and
 * is the truth: this client cannot promise a type the compiler has
 * never heard of, and it should not fail to compile for saying so.
 */
export type ZuPlainDate = typeof globalThis extends {
  Temporal: { PlainDate: new (...args: any[]) => infer Value }
}
  ? Value
  : unknown

/** `Temporal.PlainTime`, on the terms [[ZuPlainDate]] gives. */
export type ZuPlainTime = typeof globalThis extends {
  Temporal: { PlainTime: new (...args: any[]) => infer Value }
}
  ? Value
  : unknown

/** `Temporal.PlainDateTime`, on the terms [[ZuPlainDate]] gives. */
export type ZuPlainDateTime = typeof globalThis extends {
  Temporal: { PlainDateTime: new (...args: any[]) => infer Value }
}
  ? Value
  : unknown

/** `Temporal.ZonedDateTime`, on the terms [[ZuPlainDate]] gives. */
export type ZuZonedDateTime = typeof globalThis extends {
  Temporal: { ZonedDateTime: new (...args: any[]) => infer Value }
}
  ? Value
  : unknown

/** `Temporal.Duration`, on the terms [[ZuPlainDate]] gives. Named for
 * the standard's class rather than for this client's `ZuDuration`,
 * which is the other one. */
export type ZuTemporalDuration = typeof globalThis extends {
  Temporal: { Duration: new (...args: any[]) => infer Value }
}
  ? Value
  : unknown

/**
 * Every `Temporal` value this client understands, and nothing at all on
 * a program whose `lib` has no `Temporal`.
 *
 * Nothing rather than `unknown` there, because this one is a member of
 * a union: `unknown` in a union swallows it and would turn every row
 * and every parameter into `unknown` for everybody. `never` in a union
 * vanishes, so a program without `Temporal` types sees exactly what it
 * saw before this existed.
 */
export type ZuTemporalValue = typeof globalThis extends {
  Temporal: { Instant: new (...args: any[]) => infer Instant }
}
  ? Instant | ZuPlainDate | ZuPlainTime | ZuPlainDateTime | ZuZonedDateTime | ZuTemporalDuration
  : never

/**
 * A value a statement can hold, going out.
 *
 * INT64 is `bigint` and FLOAT is `number`, which is the one rule worth
 * learning before anything else here: a JavaScript number stops being
 * exact at 2^53 and zu's integers go to 2^63, so a count that came back
 * as a number would be a count you cannot trust. `bigIntMode` changes
 * that for a statement or for a connection, with the hazard it
 * documents.
 *
 * A date, a time, a timestamp and a duration are the four classes by
 * default and `Temporal` values on a connection opened with
 * `{ temporal: true }`. A time with an offset is the exception in both
 * directions: `Temporal` has no type for one, so it stays a `ZuTime`.
 *
 * BYTES is a `Uint8Array` and not a string. The bytes are octets and
 * need not be text at all, so decoding them is the caller's call to
 * make rather than this client's to make for them.
 *
 * DECIMAL is a `ZuDecimal` and not a `number`, for the reason INT64 is
 * not one and a stronger one: a tenth is not a binary fraction, so a
 * price that came back as a number would not be the price, and how many
 * places it is known to would be gone as well.
 */
export type ZuValue =
  | null
  | boolean
  | number
  | bigint
  | string
  | ZuNode
  | ZuRel
  | ZuPath
  | ZuDecimal
  | ZuDate
  | ZuTime
  | ZuTimestamp
  | ZuDuration
  | ZuTemporalValue
  | Uint8Array
  | ZuValue[]
  | { [field: string]: ZuValue }

/**
 * A value a statement can be given, coming in.
 *
 * Wider than what comes out, because a `number` that is whole binds as
 * INT64 and `undefined` binds as null, which is what makes an optional
 * field of a plain object pass straight through. Negative zero is the
 * exception and binds as FLOAT64: no INT64 is negative zero, so binding
 * it as one throws away the sign the caller went out of their way to
 * write. A `Temporal` value binds as the zu value it is on every
 * connection, whether or not the connection asked for `Temporal` on the
 * way out, because recognizing one costs a property read and refusing
 * one would be a rule nobody could guess.
 *
 * A `Uint8Array` binds as BYTES, and it is the only typed array that
 * binds at all: an `Int32Array` is a buffer somebody meant to load
 * rather than a value a statement holds, so it is refused instead of
 * being read as the empty object it has no properties to be.
 *
 * A `ZuDecimal` binds as DECIMAL and is the only way to send one. A
 * `number` never becomes one, because a caller who wrote `0.1` gave the
 * double that is not a tenth, and reading it as a decimal would put a
 * number nobody wrote into the query.
 */
export type ZuParam =
  | null
  | undefined
  | boolean
  | number
  | bigint
  | string
  | ZuDecimal
  | ZuDate
  | ZuTime
  | ZuTimestamp
  | ZuDuration
  | ZuTemporalValue
  | Uint8Array
  | ZuParam[]
  | { [field: string]: ZuParam }

/**
 * A value an appender takes, which is narrower than what a statement
 * takes.
 *
 * A column of an appender has one type, read from the table when the
 * appender opened, and every value in it is that type. So there is no
 * `null` here: a column that holds nulls cannot be appended to at all
 * and the appender says so when it opens, and `undefined` in a row is a
 * value the caller forgot rather than a null they meant. There are no
 * lists and no objects either, because a property column holds a scalar.
 *
 * BYTES is a `Uint8Array`, which is the one type here that no statement
 * parameter can be, and INT64 is a `bigint` or a whole `number` below
 * 2^53. A number past that is refused rather than rounded, because past
 * 2^53 a number no longer names one integer.
 */
export type ZuAppendValue =
  | boolean
  | number
  | bigint
  | string
  | Uint8Array
  | ZuDate
  | ZuTime
  | ZuTimestamp
  | ZuDuration
  | ZuTemporalValue

/**
 * One value of a registered frame's column, when the column is written
 * as a plain array.
 *
 * The same values an appender takes, without the bytes: a frame column
 * is a run of values the engine reads where it lies, and byte strings
 * are not a run of anything, so a BYTES column is refused rather than
 * copied into a shape it does not have. There is no `null` either, for
 * the reason there is none in a row of an appender.
 */
export type ZuFrameValue =
  | boolean
  | number
  | bigint
  | string
  | ZuDate
  | ZuTime
  | ZuTimestamp
  | ZuDuration
  | ZuTemporalValue

/**
 * One column of a registered frame.
 *
 * A typed array is the shape that costs nothing: the engine reads it
 * where it lies and no byte of it is copied. A plain array is read into
 * buffers of this client's own, because an array holds values of the
 * runtime rather than numbers, and its first value settles what the
 * column holds.
 */
export type ZuFrameColumn =
  | Int8Array
  | Uint8Array
  | Uint8ClampedArray
  | Int16Array
  | Uint16Array
  | Int32Array
  | Uint32Array
  | Float32Array
  | Float64Array
  | BigInt64Array
  | BigUint64Array
  | readonly ZuFrameValue[]

/**
 * An Arrow table or record batch, described by its shape rather than by
 * its class.
 *
 * Structural on purpose. `apache-arrow` is not a dependency of this
 * client and should not have to be: recognizing a table by the two
 * things every version of it has means a caller's copy of that library
 * and this client's are never two copies of one package disagreeing
 * about `instanceof`, and it means anything else that speaks the same
 * shape works too.
 */
export interface ZuArrowTable {
  readonly schema: { readonly fields: readonly { readonly name: string }[] }
  getChildAt(index: number): unknown
}

/**
 * Columns the caller already holds, ready to be registered under a name.
 *
 * An Arrow table, or an object of column name to values. Both are read
 * where they lie wherever there is one run of bytes to read: the two
 * cases that copy are an Arrow column that arrived in several chunks,
 * which is concatenated once, and a plain JavaScript array, which was
 * never a column of numbers to begin with.
 */
export type ZuFrame = ZuArrowTable | Record<string, ZuFrameColumn>

/**
 * An edge list, as the pairs of row numbers it is.
 *
 * Rows are numbered from zero in the order their columns were written,
 * because at load time a row has no other name. The flat spelling is
 * there for a program that built its edges in memory and would rather
 * not make a million two element arrays to hand them over: two elements
 * an edge, read in one pass.
 */
export type ZuEdges = readonly (readonly [number, number])[] | Int32Array | Uint32Array

/**
 * What a load writes, and how much of it.
 */
export interface ZuLoadOptions {
  /** The node table, which gets a row per element of every column. */
  readonly nodes: string
  /** The rel table holding the edges between those rows. `rel` by default. */
  readonly rels?: string
  /** The node table's properties, as column name to values. */
  readonly columns?: Readonly<Record<string, ZuFrameColumn>>
  /** The edges, as pairs of row numbers. */
  readonly edges?: ZuEdges | null
  /**
   * How many rows the node table has.
   *
   * Read off the columns when there are any, so this is for the load
   * that writes a graph with no properties at all, and a check on the
   * columns when both are given.
   */
  readonly rows?: number
}

/**
 * What went into a load.
 */
export interface ZuLoadStats {
  readonly nodes: number
  readonly rels: number
  readonly columns: number
}

/**
 * A walk through the graph: nodes and edges, alternating, a node at
 * each end.
 *
 * The two lists are kept apart rather than interleaved, because the
 * question a caller asks is almost always about one of them. A path of
 * one node has no edges and is the shortest there is.
 */
export interface ZuPath {
  readonly nodes: ZuNode[]
  readonly rels: ZuRel[]
}

/**
 * Something the engine wants to say about a statement that ran anyway.
 *
 * A notice is a completion condition of its own, so it carries a
 * GQLSTATUS the same way a failure does. The one raised today is
 * `01G11`, which says an aggregate ignored a null.
 */
export interface ZuNotice {
  readonly code: string
  readonly condition: string
  readonly message: string
  readonly docUrl: string
}

/**
 * What a column of a columnar read turned out to hold.
 *
 * Narrower than the type the statement declared, because the question
 * here is which buffer arrived: a time with an offset and a time
 * without are the same 64 bit cells, and the offset rides beside as
 * `zone`. `value` is the fallback for what no fixed width cell covers,
 * which is nodes, rels, paths, lists and records, and `null` is a
 * column that held nothing else.
 *
 * `bytes` arrives in the two buffers `string` arrives in and is not
 * one: the bytes are octets and a reader that decoded them as text
 * would be handed something it cannot decode, which is why the two
 * have separate names for one layout.
 *
 * This is what arrived rather than what the statement declared, and the
 * two differ for the temporal types today. The engine's columnar sink
 * has no buffer for days, nanoseconds or months, so a date, a time or a
 * duration sometimes comes over as the values themselves, and which of
 * the two a statement gets is the plan's business rather than the
 * caller's. Such a column is `value` with its `ZuDate` and `ZuDuration`
 * objects in `items`, not `date` with an empty `values`, so that a
 * switch on `type` always lands on a field that holds something.
 */
export type ZuColumnType =
  | 'null'
  | 'bool'
  | 'int'
  | 'float'
  | 'string'
  | 'bytes'
  | 'date'
  | 'time'
  | 'datetime'
  | 'duration'
  | 'value'

/**
 * One column of a result, as the buffer holding it.
 *
 * Every field is present on every column and holds null where it does
 * not apply, so reading one is a switch on `type` rather than a series
 * of tests for what is there. Which field carries the values follows
 * from the type: `values` for everything of a fixed width, `data` and
 * `offsets` for strings and byte strings, `items` for what no buffer
 * covers, and none of them for a column of nulls.
 *
 * The buffers are the engine's own, handed over rather than copied, and
 * they are laid out the way Arrow lays them out: values end to end, a
 * boolean as one bit a row, a string column as its bytes and `length +
 * 1` offsets into them, where row `i` spans `offsets[i]` to `offsets[i
 * + 1]`.
 */
export interface ZuColumn {
  readonly name: string
  readonly type: ZuColumnType
  readonly length: number
  /**
   * The cells, for a column of a fixed width: `BigInt64Array` for
   * integers, nanoseconds and months, `Float64Array` for floats,
   * `Int32Array` for days, and a `Uint8Array` of packed bits for
   * booleans, least significant bit first.
   */
  readonly values: BigInt64Array | Float64Array | Int32Array | Uint8Array | null
  /**
   * The bytes of every value end to end, for a `string` or a `bytes`
   * column.
   */
  readonly data: Uint8Array | null
  /**
   * `length + 1` offsets into `data`, for a `string` or a `bytes`
   * column. Narrow until the bytes pass what a 32 bit offset
   * addresses, which is the difference Arrow calls Utf8 against
   * LargeUtf8.
   */
  readonly offsets: Int32Array | BigInt64Array | null
  /** The values themselves, for a column of type `value`. */
  readonly items: ZuValue[] | null
  /**
   * One bit a row, least significant bit first, set meaning the row has
   * a value. Null when every row has one, which is the common case and
   * the one where a reader gets to skip the test.
   */
  readonly validity: Uint8Array | null
  /** How many rows are null, which is zero when `validity` is null. */
  readonly nulls: number
  /**
   * What one cell counts: `days`, `nanos` or `months`. Null where there
   * are no cells to count, which includes a temporal column that
   * arrived as a `value` column.
   */
  readonly unit: 'days' | 'nanos' | 'months' | null
  /** Minutes east of UTC, for a column of zoned times or datetimes. */
  readonly zone: number | null
}

/**
 * A whole result read down its columns.
 *
 * `rows` is every column's length, and is the answer for a statement
 * that projected nothing at all. `gqlstatus` and `notices` are the
 * statement's, exactly as they are on the rows.
 */
export interface ZuColumnar {
  readonly rows: number
  readonly columns: ZuColumn[]
  readonly gqlstatus: string
  readonly notices: ZuNotice[]
}

/**
 * A whole result as Arrow, in the bytes Arrow ships between processes.
 *
 * The same buffers a columnar read hands over, with the schema written
 * beside them, so `tableFromIPC(read.ipc)` is the whole of the reading
 * code and every Arrow implementation is a reader. A result with no rows
 * is a schema and one empty batch rather than nothing at all, so the
 * columns are known either way.
 */
export interface ZuArrow {
  /**
   * The stream, as one buffer: a schema message and then a message a
   * batch. It is the addon's own allocation handed over rather than
   * copied, and it detaches when posted to a worker, which is what makes
   * a result cross a thread without being cloned.
   */
  readonly ipc: Uint8Array
  /** How many rows are in it, which the batches also add up to. */
  readonly rows: number
  readonly gqlstatus: string
  readonly notices: ZuNotice[]
}

/**
 * What a statement read as Arrow takes beside its parameters.
 */
export interface ZuArrowOptions extends ZuStatementOptions {
  /**
   * How many rows one record batch holds. Arrow's own 65,536 by
   * default, which is what a reader expects and what keeps a batch
   * inside a cache.
   *
   * The arrays are built whole either way and a batch is a slice of
   * them, so this costs nothing to change and buys nothing to tune. It
   * is worth naming when the reader on the other side has a size of its
   * own, or when the batches are going somewhere one at a time.
   */
  readonly batchRows?: number
}

/**
 * The rows a statement gave back.
 *
 * An array, so iterating it is `for (const row of rows)` and nothing
 * else. What a wrapper object would have carried is carried as
 * properties beside the elements: `columns` for the projection in the
 * order it was written, `gqlstatus` for the condition the statement
 * completed with, and `notices` for what it wanted to say on the way.
 */
export interface ZuRows<Row = Record<string, ZuValue>> extends Array<Row> {
  readonly columns: string[]
  readonly gqlstatus: string
  readonly notices: ZuNotice[]
}

/**
 * One batch of a streamed result.
 *
 * The rows of a whole result with the same array trick and one fewer
 * property: `columns` is the statement's projection and is the same on
 * every batch of one stream, and what a statement completed with is not
 * known until it has, so it is on the summary rather than here.
 */
export interface ZuBatch<Row = Record<string, ZuValue>> extends Array<Row> {
  readonly columns: string[]
}

/**
 * What a streamed statement did, known once it has ended.
 *
 * The rows are gone by then, which is the point of streaming, so this
 * is what is worth keeping about a result nobody held: what it
 * projected, how much of it was read, whether the reader stopped it
 * early, and what the engine wanted to say along the way.
 */
export interface ZuSummary {
  readonly columns: string[]
  /** How many rows were handed over, which is fewer than the statement
   * would have returned when the reader stopped early. */
  readonly rows: number
  readonly stopped: boolean
  /**
   * Whether the rows arrived as they were made, rather than the
   * statement running whole and being handed over in batches
   * afterwards. A statement that has to see every row before it can
   * give one, which is `ORDER BY`, `DISTINCT`, the aggregates and
   * anything that writes, is the second kind, and so is a plan the
   * pipeline executor does not take. The loop over it reads the same
   * either way, so this is here for a caller measuring where the time
   * went rather than for one deciding what to do next.
   */
  readonly streamed: boolean
  readonly notices: ZuNotice[]
}

/**
 * One operator of a plan, and everything under it.
 *
 * The tree runs the way the rows do: a parent pulls from its children,
 * so the leaves are the scans and the root is whatever the statement
 * ends with.
 */
export interface ZuPlanNode {
  /** The operator: `Scan`, `Expand`, `Filter`, `Project` and the rest. */
  readonly op: string
  /**
   * What the listing calls it, which is `op` with the bracket in front
   * of it where there is one, so an OPTIONAL MATCH expand is an
   * `Expand` named `OptionalExpand`.
   */
  readonly name: string
  /** The bracket this operator is inside, and null for a plain match. */
  readonly bracket: 'Optional' | 'Semi' | 'Anti' | 'Mark' | null
  /**
   * What it is working on, written the way the statement wrote it: the
   * tables a scan reads, the pattern an expand walks, the predicate a
   * filter asks. Empty where the operator has nothing to name.
   */
  readonly detail: string
  /** The variables it introduces, in the order it binds them. */
  readonly binds: string[]
  /**
   * The tables it touches: node tables for a scan, rel tables for an
   * expand, both for an insert, and none anywhere else.
   */
  readonly tables: string[]
  readonly children: ZuPlanNode[]
}

/**
 * A query written where a value belongs, planned on its own.
 *
 * `reads` is what it reads from the query around it, and empty is the
 * whole test for whether it runs once: a subquery that reads nothing
 * answers the same value for every row, and one that reads a name runs
 * per row. `exists` is true where what was written around it asks only
 * whether it answered a row.
 */
export interface ZuScalarPlan {
  readonly reads: string[]
  readonly exists: boolean
  readonly plan: ZuPlan
}

/**
 * What a statement would do, without doing it.
 *
 * A tree and a rendering of it. `text` is what the engine prints, so a
 * listing logged from Node is the listing the shell shows, and the tree
 * is for the questions a program asks: which tables were touched, how
 * deep the expands go, whether the scan reached an index.
 */
export interface ZuPlan {
  /**
   * The top operator, and null for the plan with no operators at all,
   * which is the one row a statement with no clauses runs over.
   */
  readonly root: ZuPlanNode | null
  /** The columns the statement answers with, in the order it wrote them. */
  readonly columns: string[]
  /** The parameters it wants, without the `$` they are written with. */
  readonly params: string[]
  /** What compiling it raised, which is empty for most statements. */
  readonly notes: string[]
  readonly scalars: ZuScalarPlan[]
  /** The listing, indented, as `EXPLAIN` prints it. */
  readonly text: string
}

/**
 * One operator of a profiled run, and what the counters saw of it.
 */
export interface ZuOp {
  readonly op: string
  readonly detail: string
  /** How many chunks it produced. */
  readonly pulls: number
  /** Values produced across every pull. Over `pulls` that is the
   * average vector length, which is the factorization statistic. */
  readonly rows: number
  /**
   * The rows those values stand for with the factorization multiplied
   * out. On a chain it is `rows`, and on a star it is the product over
   * every vector still unflat beside this one, which is the count the
   * optimizer was estimating.
   */
  readonly flat: number
  /**
   * What the optimizer expected, and null for the operators that pass
   * their input through rather than producing rows of their own.
   */
  readonly estimate: number | null
  /** The most rows the optimizer's ceiling allowed, where the
   * statistics were there to set one. */
  readonly bound: number | null
  /** Self time in nanoseconds, with the children's excluded. */
  readonly nanos: number
  /**
   * How wrong the estimate was: `max(estimate/rows, rows/estimate)`,
   * both floored at one row. An operator the optimizer got right is 1,
   * and null wherever `estimate` is.
   */
  readonly qerror: number | null
}

/**
 * One stage of a profiled run: the operators bottom-up and the sink
 * that took their rows.
 */
export interface ZuStage {
  readonly sink: string
  /** How many rows the sink was handed. */
  readonly rows: number
  /** Wall time of the whole stage in nanoseconds, sink included. */
  readonly nanos: number
  readonly ops: ZuOp[]
}

/**
 * What a statement did, with the counters on.
 *
 * The rows are not here: a profile is about the run rather than the
 * answer, and keeping both would make the measurement pay for the thing
 * it is measuring. `text` is the listing `EXPLAIN ANALYZE` prints.
 */
export interface ZuProfile {
  readonly stages: ZuStage[]
  /** Every stage end to end, in nanoseconds. */
  readonly nanos: number
  readonly text: string
}

/**
 * What a watch on a running statement takes.
 */
export interface ZuProgressOptions {
  /**
   * How long to wait between looks, in milliseconds. A tenth of a
   * second by default, which is about where a person stops reading a
   * number and starts seeing it move.
   *
   * What one look costs is an atomic read, so this is a question about
   * how often the callback should run rather than about how much the
   * watch costs the statement.
   */
  readonly everyMs?: number
}

/**
 * A watch on a running statement, which is stopped by `stop()` or by
 * leaving the scope of a `using`.
 *
 * Stopping twice does nothing, and so does stopping one that has
 * already been left behind.
 */
export interface ZuProgress extends Disposable {
  /** Stops the watch. The callback is not called again. */
  stop(): void
}

/**
 * What a streamed statement takes beside its parameters.
 */
export interface ZuStreamOptions extends ZuStatementOptions {
  /**
   * How many rows a batch may hold. The engine's own vector by
   * default, which is the unit it already works in and the one that
   * costs nothing to hand over. Name a size when the rows are going
   * somewhere with a size of its own, an Arrow record batch or an
   * HTTP chunk.
   *
   * A ceiling and not a promise: batches are cut out of rows that have
   * already been made, so the last piece of a run of them is whatever
   * was left, and a size above the engine's vector gets the vector. It
   * is what bounds how much a reader holds at once, which is the
   * question a caller is asking when they name one.
   */
  readonly batchRows?: number
}

/**
 * How INT64 is spelled on the way out.
 *
 * `bigint` is the default and is the only one of the two that is always
 * right, because zu's integers go to 2^63 and a JavaScript number stops
 * telling one integer from the next at 2^53.
 *
 * `number` is for the program that has already decided its integers are
 * small: ids that count in millions, a `count(*)` over a table that
 * will never be one, a row about to be handed to `JSON.stringify`,
 * which cannot serialize a `bigint` at all. It is worth knowing exactly
 * what is being traded for that. Which integers a database holds is a
 * property of the data and not of the program, so a query that returned
 * numbers for every row of a test database is a query that can meet a
 * larger one in production. This client refuses that row rather than
 * rounding it, with a `ZuUsageError` naming the column and the value,
 * so the failure is loud and local rather than an answer that is quietly
 * off by one. It is still a failure that arrives at read time, on a
 * machine that is not yours, which is why the default is the other one.
 *
 * The mode reaches the INT64 columns of a result and nothing else. A
 * node's `offset`, an edge's `src`, `dst` and `ord`, and the nanosecond
 * counts of the temporal classes stay `bigint` in both modes, because
 * they are properties of classes the addon registers once and not
 * values a statement can respell.
 */
export type ZuBigIntMode = 'bigint' | 'number'

/**
 * What a statement takes beside its parameters.
 *
 * An object rather than a bare signal, because the options that follow
 * it belong in the same place and a third argument that changes meaning
 * is one nobody can read at a call site.
 */
export interface ZuStatementOptions {
  /**
   * How INT64 comes back from this statement. `bigint` unless the
   * connection was opened with the other mode, and either way a
   * statement may name the one it wants.
   */
  readonly bigIntMode?: ZuBigIntMode
  /**
   * Stops the statement when it fires, through the same interrupt a
   * shell answers `Ctrl-C` with: the executor notices at the boundary it
   * was already stopping at, the statement ends, and the connection is
   * exactly as it was. The promise rejects with whatever the signal
   * gives as its reason, which is what `fetch` does, so
   * `AbortSignal.timeout(50)` rejects with a `TimeoutError` and
   * `controller.abort(new MyError())` rejects with `MyError`.
   *
   * A signal that has already fired stops the statement before the
   * engine sees it at all.
   */
  readonly signal?: AbortSignal
}

/**
 * What a transaction takes when it starts.
 */
export interface ZuTransactionOptions {
  /**
   * Starts it `READ ONLY`, which the engine refuses a write inside of
   * at the statement that writes rather than at this call.
   *
   * Worth asking for on a span that only reads, because saying so is
   * how a statement that was not meant to write is stopped by the
   * database rather than by review.
   */
  readonly readOnly?: boolean
}

/**
 * What a failed call throws.
 *
 * An ordinary `Error`, so every `catch`, logger and unhandled rejection
 * handler already knows what to do with it. What makes it a zu error is
 * the fields, and none of them has to be parsed back out of the
 * message: `code` picks the branch, `line` and `column` underline the
 * token, `retryable` decides whether a retry loop goes round again.
 */
export interface ZuError extends Error {
  /**
   * The condition's class, written out: `ZuSyntaxError`,
   * `ZuDataError`, `ZuTransactionError`, `ZuConnectionError`,
   * `ZuInterrupted`, `ZuUsageError`, `ZuInternalError`, or `ZuError`
   * for a condition in a class none of those name.
   */
  readonly name: string
  /** Whether running the same statement again could succeed. */
  readonly retryable: boolean
  /**
   * The GQLSTATUS, five characters. Absent on a mistake this client
   * caught before the engine saw it, which is why a caller mapping
   * codes to branches has to tell a missing one from an unknown one.
   */
  readonly code?: string
  /** The standard's own words for that code. */
  readonly condition?: string
  readonly severity?: 'success' | 'noData' | 'warning' | 'informational' | 'exception'
  readonly docUrl?: string
  /** Where in the statement, for a condition that happened somewhere. */
  readonly line?: number
  readonly column?: number
  readonly offset?: number
  /** The whole line `column` indexes into, for underlining it. */
  readonly excerpt?: string
}
/**
 * Rows on their way into a table, buffered until they are flushed.
 *
 * Take one with `Connection.appender`, append rows to it, and close
 * it. What is buffered is columnar and typed from the table's own
 * columns, read when the appender opened, so a value that does not
 * belong in a column is refused by the call that appended it rather
 * than at the flush that would have carried it, and the message names
 * the column it did not fit.
 */
export declare class Appender {
  /** The table these rows are going into. */
  get table(): string
  /** Rows buffered and not yet written. */
  get buffered(): number
  /** Rows this appender has committed, across every flush. */
  get committed(): number
  /** Whether this appender has been closed. */
  get closed(): boolean
  /**
   * Appends one row, which is one value per column of the table, in
   * the order the table declares them.
   *
   * Synchronous, and the only synchronous call in this client: the
   * values go into memory and nothing else happens, so this is a
   * conversion and a push per column. Being synchronous it throws
   * rather than rejecting, with the same `ZuUsageError` every other
   * refusal here carries.
   *
   * A row of the wrong width, or with a value that does not fit the
   * column, is refused with nothing of it kept, so the appender is
   * still usable once the caller has fixed the row.
   */
  appendRow(row: readonly ZuAppendValue[]): void
  /**
   * Appends every row of an array of rows.
   *
   * The same thing in a loop, and worth a call of its own because it
   * is one check and one lock for the batch rather than one per row.
   * A row that is refused stops the call where it was refused and the
   * rows before it stay buffered: nothing here is a transaction until
   * the flush, and throwing away work the caller can keep would not
   * make it one. What it answers is how many rows went in, which is
   * where a caller who caught the refusal starts again.
   */
  appendRows(rows: readonly (readonly ZuAppendValue[])[]): number
  /**
   * Writes every buffered row and makes it readable, and answers how
   * many rows this appender has committed in all.
   *
   * One commit, whatever the buffer holds: the values are sealed into
   * the file, one frame naming them is synced to the log, and the
   * fold that follows puts them where every query looks. On return
   * the buffer is empty and the rows are there. A flush with nothing
   * buffered touches no file, so a loader can flush on a timer
   * without writing empty commits.
   *
   * A flush that fails keeps its rows, so that what did not go in is
   * still there to be looked at and tried again.
   */
  flush(): Promise<number>
  /**
   * Flushes what is left and answers how many rows this appender
   * committed in all.
   *
   * Closing twice is not an error and writes nothing the second
   * time, because an `await using` that closed early would otherwise
   * fail on the way out.
   */
  close(): Promise<number>
  /**
   * The close `await using` calls, which is the intended way to
   * scope an appender.
   *
   * It flushes, whether the block ended well or badly, which is the
   * opposite of what the disposal of a transaction here does and is
   * the same answer the Python client gives. The two differ because
   * the question differs: a transaction that leaves its scope
   * unfinished is a unit of work nobody completed, and a buffer that
   * leaves its scope unwritten is a loader that read a million rows
   * and threw them away. A caller who wants the rows gone writes
   * `discard()` and gets exactly that.
   *
   * It is also reachable as `Symbol.asyncDispose`, which is what
   * `await using` actually looks for and which [`wire_disposal`] puts
   * on every appender as it is made.
   */
  dispose(): Promise<number>
  /**
   * Throws away what is buffered and answers how many rows that was.
   *
   * The way out of a load that went wrong halfway. A caller who has
   * noticed that the rows are wrong wants them gone, and closing
   * would write them. Rows an earlier flush committed are committed,
   * and this does not reach them.
   */
  discard(): number
}

/**
 * One connection to one database.
 *
 * Statements run on it in order, one at a time. It reads the database
 * as of when it was opened, which is why a program that wants to see
 * another writer's work takes a new connection rather than waiting on
 * this one.
 */
export declare class Connection {
  /** Where the database this is connected to lives. */
  get path(): string
  /** Whether this connection refuses every statement that writes. */
  get readOnly(): boolean
  /**
   * Whether the database behind it is in memory rather than on
   * disk, in which case nothing survives the last connection to it.
   */
  get memory(): boolean
  /** Whether the connection is still open. */
  get open(): boolean
  /**
   * Whether an explicit transaction is running on this connection.
   *
   * True inside a `transaction()` and true after a `START
   * TRANSACTION` written by hand, because it is asked of the session
   * rather than counted here. A statement written on its own runs in
   * a transaction of its own and this stays false for it: what it
   * answers is whether a span is open, not whether anything is
   * atomic.
   */
  get inTransaction(): boolean
  /**
   * How many rows the statement running on this connection has read
   * out of storage, for showing a person that something is
   * happening.
   *
   * Rows read rather than rows answered, because the statement
   * somebody is waiting on is exactly the one that reads a hundred
   * million rows to answer one. It starts at zero at each statement
   * and holds its last value once one ends.
   *
   * This is the one thing on a connection that is worth reading
   * while a statement runs, and it is answered the way
   * [`Connection::open`] is: an atomic beside the lock rather than a
   * question through it. So the loop's thread gets its answer while
   * the threadpool thread is still scanning, and `progress()` is the
   * timer written around it.
   *
   * A number rather than a bigint, like every other count this
   * client makes rather than reads out of a column: a statement that
   * had read 2^53 rows would have been running for weeks.
   */
  get rowsRead(): number
  /**
   * Starts a transaction and hands it back.
   *
   * It starts here rather than at the first statement inside it, so a
   * transaction that cannot start says so at the line that asked. A
   * connection is inside one transaction at a time and asking for a
   * second while one is open is refused by the engine rather than
   * nested, because a transaction inside a transaction is a promise
   * this database does not make.
   *
   * ```js
   * await using tx = await conn.transaction()
   * await conn.exec('INSERT (a:account {uid: 1, balance: 100})')
   * await conn.exec('INSERT (b:account {uid: 2, balance: 0})')
   * await tx.commit()
   * ```
   *
   * The `await using` is the rollback nobody remembers to write. It
   * undoes the transaction unless the block committed it, which is
   * the opposite of what Python's `with` block does here and is the
   * only honest reading in JavaScript: a disposal is not told whether
   * the scope it is leaving threw, so a disposal that committed would
   * commit half of the work of a block that failed.
   */
  transaction(options?: ZuTransactionOptions | null): Promise<Transaction>
  /**
   * Opens an appender on `table` and hands it back.
   *
   * The bulk-load path. A load written as statements pays a commit
   * per row, and an appender pays one per flush, which is the whole
   * difference between loading a million rows in an afternoon and
   * loading them in a minute.
   *
   * ```js
   * await using rows = await conn.appender('person')
   * for (const [id, name] of people) rows.appendRow([id, name])
   * await rows.flush()
   * ```
   *
   * The table has to exist, and its columns are read here, so a
   * table nothing declares and a column of a type the ingest cannot
   * carry are both refused at this call rather than at the flush a
   * million rows later.
   */
  appender(table: string): Promise<Appender>
  /**
   * Registers columns the caller already holds as a table called
   * `name`, and answers how many rows it has.
   *
   * The zero-copy way in. Nothing is read into the database: the
   * engine is told where the caller's buffers are, and a statement
   * that matches the name scans them where they lie, so registering
   * ten million rows costs a description of their columns rather than
   * ten million writes.
   *
   * ```js
   * await conn.register('people', arrow.tableFromArrays({ id, name }))
   * const rows = await conn.query('MATCH (p:people) RETURN p.name AS name')
   * ```
   *
   * An Arrow table or record batch, which is what `apache-arrow` and
   * everything built on it hands out, or an object of column name to
   * values. The values of that object are typed arrays where the
   * caller has them, which is the zero-copy shape, and plain arrays
   * where they do not, which is read into buffers of this client's
   * own because an array holds values of the runtime rather than
   * numbers.
   *
   * A frame is a view and not a snapshot: write into the array behind
   * it and the next statement answers what is there now. It belongs
   * to this connection, is never written to the database, and no
   * other program opening the same file sees it. Nothing writes to
   * one either, so a statement that inserts into a registered name is
   * refused with the reason.
   */
  register(name: string, data: ZuFrame): Promise<number>
  /**
   * Takes a registered frame's name away and gives the bytes back.
   *
   * The bytes go when the last statement reading them lets go, which
   * is usually now and is never before: a frame a running statement
   * is still scanning is held until it ends.
   */
  unregister(name: string): Promise<void>
  /**
   * The names frames are registered under on this connection, sorted.
   *
   * A method rather than a getter, and asynchronous like everything
   * else here, because reading them takes the connection's lock and
   * nothing on this class waits on the event loop.
   */
  registered(): Promise<string[]>
  /**
   * Runs one statement and gives back its rows.
   *
   * The parameters are named, never positional, because zuQL names
   * them: `$id` in the statement is `id` in the object. A name the
   * statement does not use is an error from the engine rather than a
   * value quietly ignored.
   */
  query<Row = Record<string, ZuValue>>(statement: string, params?: Record<string, ZuParam> | null, options?: ZuStatementOptions | null): Promise<ZuRows<Row>>
  /**
   * Runs one statement for its effect and gives back nothing.
   *
   * The same call as [`Connection::query`] with the rows dropped,
   * which is what a schema statement or a write wants: a result nobody
   * reads still costs a row object per row on the way out.
   */
  exec(statement: string, params?: Record<string, ZuParam> | null, options?: ZuStatementOptions | null): Promise<void>
  /**
   * Runs one statement and gives back its columns rather than its
   * rows.
   *
   * The same statement as [`Connection::query`], read down instead
   * of across: what comes back is one buffer a column, in the layout
   * Arrow already uses, and no object a row. That is the way out for
   * anything that is going to be counted, plotted or handed to a
   * dataframe, and it is the way out that does not build a million
   * JavaScript values on the way.
   */
  columnar(statement: string, params?: Record<string, ZuParam> | null, options?: ZuStatementOptions | null): Promise<ZuColumnar>
  /**
   * Runs one statement and gives back the bytes of an Arrow IPC
   * stream.
   *
   * ```js
   * import { tableFromIPC } from 'apache-arrow'
   * const read = await conn.arrow('MATCH (a:account) RETURN a.name AS name, a.balance AS balance')
   * const table = tableFromIPC(read.ipc)
   * ```
   *
   * The same buffers [`Connection::columnar`] hands over, with the
   * schema written beside them in the format every Arrow
   * implementation already reads. That is the difference worth
   * knowing: `columnar` is the fastest way out and leaves the caller
   * to say what each buffer means, and this is the one where the
   * result arrives as a table, a dataframe or a DuckDB relation with
   * no code in between.
   *
   * The translation lives in the engine and is the same one the
   * Python client exports through, so a node column names its table
   * in both and a year-month duration is a month interval in both.
   */
  arrow(statement: string, params?: Record<string, ZuParam> | null, options?: ZuArrowOptions | null): Promise<ZuArrow>
  /**
   * Compiles a statement, pins it, and hands back something that
   * runs it.
   *
   * ```js
   * await using find = await conn.prepare('MATCH (p:person) WHERE p.id = $id RETURN p.name AS name')
   * for (const id of ids) console.log(await find.query({ id }))
   * ```
   *
   * What this buys is not what it buys in a driver. A driver prepares
   * to save a round trip and this database has none, and the plan for
   * a statement is cached by its text either way, so a loop that
   * writes the same query twice is not compiling it twice whether or
   * not anybody prepared it. What preparing buys here is the compile
   * happening at the line that asked for it, so a statement that does
   * not compile is a failure at startup rather than on the first
   * request that used it, and the parameter names coming back, so a
   * program can bind by what the statement actually wants rather than
   * by what somebody remembered writing.
   *
   * The id maps back to the text rather than to a plan, so a prepared
   * statement crossing a catalog change recompiles instead of running
   * a plan for a table that has since changed shape.
   */
  prepare(statement: string): Promise<Prepared>
  /**
   * The plan this connection would run for a statement, without
   * running it.
   *
   * ```js
   * const plan = await conn.explain('MATCH (p:person) WHERE p.id = $id RETURN p.name AS name')
   * console.log(plan.text)
   * ```
   *
   * A tree and a rendering of it, because the two questions a plan
   * gets asked want different things: a person reading it wants the
   * listing, and a program asking whether the scan reached an index
   * or which tables were touched wants operators it can walk. They
   * are one plan printed two ways rather than two answers that can
   * drift, since `text` is what the engine renders from the same
   * tree.
   *
   * No parameters, because a plan does not depend on the values bound
   * to it: it depends on the names, and those are in `params`. A
   * statement that does not compile fails here, which is most of why
   * this is worth calling.
   */
  explain(statement: string): Promise<ZuPlan>
  /**
   * Runs a statement with the counters on and gives back what they
   * saw, rather than the rows.
   *
   * ```js
   * const run = await conn.profile('MATCH (p:person)-[:knows]->(q) RETURN q.name AS name')
   * console.log(run.text)
   * ```
   *
   * This is the call for a statement that is slower than its plan
   * says it should be. Every operator carries what it really
   * produced beside what the optimizer expected, and `qerror` is the
   * ratio between them, so the operator whose estimate was wrong is
   * the one to look at and `nanos` says whether being wrong cost
   * anything.
   *
   * It costs the execution, since the way to find out what a
   * statement does is to do it. A statement that writes is refused,
   * because profiling it would apply the write.
   */
  profile(statement: string, params?: Record<string, ZuParam> | null, options?: ZuStatementOptions | null): Promise<ZuProfile>
  /**
   * Another connection to the same database, made from this one.
   *
   * This is how a pool is written. `connect()` opens the file again
   * and looks the database up by path; this forks off the one this
   * connection already holds, which costs a schema load and no
   * lookup, and works on a database in memory, where there is no
   * path to open a second time.
   *
   * ```js
   * await using other = await conn.duplicate()
   * const rows = await other.query('MATCH (p:person) RETURN p.name AS name')
   * ```
   *
   * The two are connections in every sense rather than two names
   * for one. Each has its own prepared statements, its own caches
   * and its own transaction, so a task taking one from a pool is not
   * in whatever transaction the last borrower left open, and closing
   * one does not close the other. What they share is the write side:
   * they queue behind each other to write and each sees what the
   * other has committed, which is what two connections to one file
   * have always done.
   *
   * Other clients call this `cursor()`, after the way every
   * embedded database has spelled it for thirty years. That name is
   * taken here by [`Connection::cursor`], which is a cursor over the
   * rows of one statement and a different thing entirely, so this
   * one says what it does.
   *
   * The switches this connection was opened with come across,
   * including how it spells the values it gives back, because a pool
   * handing out connections that answered differently from the one it
   * was seeded with would be a trap nobody would look for.
   */
  duplicate(): Promise<Connection>
  /**
   * Runs one statement and gives back a cursor over its rows.
   *
   * The pull underneath `stream`, which is what a program uses. The
   * statement does not start here: it starts on the first read, so
   * that a cursor made and not read is not a scan holding the
   * connection against every statement after it.
   */
  cursor(statement: string, params?: Record<string, ZuParam> | null, options?: ZuStreamOptions | null): ZuCursor
  /**
   * Closes the connection and releases the database.
   *
   * Closing twice does nothing the second time, which is what makes
   * `await using` safe to combine with an explicit close in a branch
   * that ran first.
   */
  close(): void
  /**
   * The disposal `await using` calls, which is the intended way to
   * scope a connection. `close` stays public for callers who cannot
   * use it.
   *
   * It is also reachable as `Symbol.asyncDispose`, which is what
   * `await using` actually looks for and which [`wire_disposal`] puts
   * on every connection as it is made.
   */
  dispose(): Promise<void>
}

/**
 * A statement the connection has compiled and pinned.
 *
 * Take one with `Connection.prepare`, run it as often as you like, and
 * close it. It runs the same three ways a connection does, `query`,
 * `exec` and `columnar`, because a prepared statement is a statement
 * and the way a caller wants its answer is not a decision the prepare
 * should have made.
 *
 * There is no `stream`. A stream is the engine's `run_streaming`, which
 * takes the text of a statement rather than a pinned id, so a streamed
 * prepared statement would be this client re-running the text behind
 * the caller's back and calling it prepared. `conn.stream(sql, params)`
 * is that, honestly spelled.
 */
export declare class Prepared {
  /** The statement, as it was written. */
  get statement(): string
  /**
   * The names this statement wants, in the order the binder assigned
   * them, and without the `$` they are written with.
   *
   * Empty for a statement that takes none. A name in here that the
   * caller does not bind is a failure at the run rather than a null,
   * which is the engine's rule and the one worth relying on.
   */
  get params(): Array<string>
  /** Whether this prepared statement has been closed. */
  get closed(): boolean
  /** Runs it and gives back its rows. */
  query<Row = Record<string, ZuValue>>(params?: Record<string, ZuParam> | null, options?: ZuStatementOptions | null): Promise<ZuRows<Row>>
  /** Runs it for its effect and gives back nothing. */
  exec(params?: Record<string, ZuParam> | null, options?: ZuStatementOptions | null): Promise<void>
  /** Runs it and gives back its columns rather than its rows. */
  columnar(params?: Record<string, ZuParam> | null, options?: ZuStatementOptions | null): Promise<ZuColumnar>
  /** Runs it and gives back the bytes of an Arrow IPC stream. */
  arrow(params?: Record<string, ZuParam> | null, options?: ZuArrowOptions | null): Promise<ZuArrow>
  /**
   * Gives the id back to the session.
   *
   * Closing twice does nothing the second time, and closing one whose
   * connection has already gone does nothing at all, because the
   * session that was holding it went with it. Both of those are what
   * makes an explicit close safe to write inside a block that an
   * `await using` is also going to leave.
   */
  close(): Promise<void>
  /**
   * The close `await using` calls, which is the intended way to scope
   * a prepared statement.
   *
   * It is also reachable as `Symbol.asyncDispose`, which is what
   * `await using` actually looks for and which [`wire_disposal`] puts
   * on every prepared statement as it is made.
   */
  dispose(): Promise<void>
}

/**
 * A transaction that has been started and not yet ended.
 *
 * Take one with `Connection.transaction`. It starts when it is taken,
 * so a transaction that cannot start says so at the line that asked,
 * and the statements that run inside it are the ones written on the
 * connection it came from.
 */
export declare class Transaction {
  /**
   * Whether this transaction was started `READ ONLY`, which the
   * engine refuses a write inside of at the statement that writes.
   */
  get readOnly(): boolean
  /**
   * Whether this transaction has already been committed or rolled
   * back.
   */
  get done(): boolean
  /**
   * Ends the transaction and keeps what it wrote.
   *
   * Doing it twice is refused rather than ignored. A second commit is
   * a program that has lost track of where its transaction ends, and
   * the statements between the two are in neither of them.
   */
  commit(): Promise<void>
  /** Ends the transaction and throws away what it wrote. */
  rollback(): Promise<void>
  /**
   * The undo `await using` calls, which is the intended way to scope
   * a transaction.
   *
   * It rolls back, and it does nothing at all when the transaction
   * has already ended, which is what makes a committed block and a
   * failed one both leave through here without saying anything.
   *
   * It is also reachable as `Symbol.asyncDispose`, which is what
   * `await using` actually looks for and which [`wire_disposal`] puts
   * on every transaction as it is made.
   */
  dispose(): Promise<void>
}

/**
 * One statement, read a batch at a time.
 *
 * This is the pull underneath the stream and not the shape a program
 * should be reaching for: `conn.stream(...)` gives back something that
 * is async-iterable, turns into the web's own `ReadableStream`, and
 * stops itself when the loop over it breaks.
 */
export declare class ZuCursor {
  /**
   * The next batch of rows, or `null` once the statement has ended.
   *
   * An array of row objects with the column names beside it, which
   * is the value `query` gives for a whole result and for the same
   * reason: what a caller does with rows is iterate them.
   */
  next(): Promise<ZuBatch | null>
  /**
   * Stops the statement and waits for it to let go of the
   * connection.
   *
   * Waits, because a stream abandoned while the next statement on
   * the same connection is already being asked for would make that
   * statement queue behind a scan nobody is reading. Stopping is not
   * a failure: the rows already handed over stand, and the summary
   * says the statement was stopped.
   */
  cancel(): Promise<void>
  /**
   * What the statement did, once it has ended, and `null` until
   * then.
   *
   * The column names are here as well as beside every batch, because
   * a statement that gave back no rows gave back no batches either
   * and its projection is still worth knowing.
   */
  get summary(): ZuSummary | null
}

/**
 * A date, as days from 1970-01-01.
 *
 * A count rather than a set of fields, which is what the engine
 * stores and what makes two dates compare as two numbers. `Temporal`
 * reached Stage 4 in March 2026 but is unflagged only in Node 26 and
 * the newest browsers, and Node 24 is still the active LTS, so this
 * is the stable type and the runtimes that have `Temporal` reach it
 * through the opt-in rather than through a type that changes shape
 * under them.
 */
export declare class ZuDate {
  days: number
  constructor(days: number)
  /**
   * The same day as a `Temporal.PlainDate`.
   *
   * For the program that wants one value converted rather than all of
   * them, which is the common one: a result is read for its ids and
   * its names and then formats the one date it is going to show. A
   * connection opened with `{ temporal: true }` does this to every
   * temporal value it gives back and this method is what it calls.
   *
   * Throws on a runtime that has no `Temporal`, naming the flag that
   * turns it on.
   */
  toTemporal(): ZuPlainDate
  /**
   * The same thing as a plain object, for the reason [`ZuNode::to_json`]
   * gives.
   */
  toJSON(): object
}

/**
 * An exact decimal: an integer of units, and how many of its digits
 * are after the point.
 *
 * A class because JavaScript has no exact number to be. A `number` is
 * an IEEE double and a tenth is not a binary fraction, so `0.1 + 0.2`
 * is not `0.3` and a price read into one is not the price. A `bigint`
 * is exact and whole, which is half of what a decimal is. So this is
 * the same decision [`ZuDate`] is: the runtime has no type for the
 * value, and inventing one that loses it would be worse than naming
 * it.
 *
 * The scale rides on the value rather than only on the column it came
 * from, because `CAST('1.20' AS DECIMAL(5, 2))` in a `RETURN` has no
 * column to ask and still has two places. `1.20` and `1.2` are the
 * same number written with different care about how well it is known,
 * they compare as the same number, and each prints back the way it was
 * written.
 */
export declare class ZuDecimal {
  /**
   * The decimal a piece of text spells, at the scale it was written
   * at, so `ZuDecimal.parse('1.20')` has two places and prints back
   * as `1.20`.
   *
   * This is the one to reach for. A decimal usually arrives written
   * down, out of a form or a config file or a column of a CSV, and
   * the text carries the scale along with the number. `of` is for a
   * caller who already holds the pair.
   *
   * An exponent is taken, because `1E3` is a number somebody writes,
   * and it moves the point rather than the value: `1.5e3` is fifteen
   * hundred at no places and not `1.500`.
   *
   * Throws on text that is not an exact number, which is a NaN, an
   * infinity, and anything with more digits than a decimal here
   * holds.
   */
  static parse(text: string): ZuDecimal
  /**
   * A decimal of `unscaled` units, each one ten to the minus
   * `scale`, so `ZuDecimal.of(120n, 2)` is `1.20`.
   *
   * Nothing is normalised: the scale given is the scale kept, and a
   * trailing nought is a digit the caller said they know.
   *
   * Throws when the pair is not one a decimal here holds, which is
   * more than thirty eight digits in the integer or a point further
   * right than any `DECIMAL(p, s)` could declare.
   */
  static of(unscaled: bigint, scale: number): ZuDecimal
  /**
   * The integer the value is counted in units of, which is `120n`
   * for `1.20`. A `bigint`, because thirty eight digits is past what
   * a `number` tells apart from its neighbours.
   */
  get unscaled(): bigint
  /**
   * How many of the digits are after the point, which is `2` for
   * `1.20`.
   */
  get scale(): number
  /**
   * The number written out, with the point where the scale says it
   * is and never an exponent. This is the lossless spelling and the
   * one `parse` reads back.
   */
  toString(): string
  /**
   * The nearest `number`, for the arithmetic JavaScript can do and
   * the chart that is going to plot it anyway.
   *
   * The conversion is where the exactness stops, and it is offered
   * rather than done because that is the caller's call to make. A
   * decimal of more than about fifteen digits does not survive it,
   * and neither does most of what the type exists for: three tenths
   * is not a double. `toString` is the one that loses nothing.
   */
  toNumber(): number
  /**
   * The number as its own text, for the reason [`ZuNode::to_json`]
   * gives and one more.
   *
   * A string rather than the two fields, because the two fields
   * include a `bigint`, which has no JSON spelling, and because the
   * text is the whole value and reads back through `parse`. A JSON
   * number would be a double again, which is the thing this type
   * exists to not be.
   */
  toJSON(): string
}

/**
 * A duration, which is a count of months or a count of nanoseconds
 * and never both.
 *
 * The two kinds do not mix, because no number of days is a month: a
 * value holding both would have to invent an answer for one month
 * after 31 January, and the standard does not ask for the invention.
 * `kind` says which one this is, and the other count is zero.
 */
export declare class ZuDuration {
  /** A duration of `months` months, which is the year-month kind. */
  static ofMonths(months: bigint): ZuDuration
  /** A duration of `nanos` nanoseconds, which is the day-time kind. */
  static ofNanos(nanos: bigint): ZuDuration
  /** Which of the two kinds this is: `yearMonth` or `dayTime`. */
  get kind(): string
  /** The months, which is zero for a day-time duration. */
  get months(): bigint
  /** The nanoseconds, which is zero for a year-month duration. */
  get nanos(): bigint
  /**
   * The same length as a `Temporal.Duration`.
   *
   * A year-month one becomes months and a day-time one becomes
   * seconds and nanoseconds, which are the fields that hold what zu
   * stores without inventing the rest: `Temporal.Duration` can carry
   * months and days at once and no zu duration ever does.
   */
  toTemporal(): ZuTemporalDuration
  /**
   * The same thing as a plain object, for the reason [`ZuNode::to_json`]
   * gives.
   */
  toJSON(): object
}

/**
 * One node of the graph.
 *
 * The table is the name written in the schema and the offset is the
 * row it sits at in that table, which together are what identifies a
 * node in zu. The offset is a `bigint` for the reason every other
 * 64-bit integer here is one.
 *
 * The 64-bit fields are held as integers and handed out as `bigint` by
 * a getter, rather than being held as a `bigint` and handed out
 * directly, because a `bigint` is a JavaScript value and a value
 * cannot be held by a struct that is built on a threadpool thread
 * where there is no environment to build one in.
 */
export declare class ZuNode {
  get table(): string
  get offset(): bigint
  /**
   * The same thing as a plain object.
   *
   * Every field here is a getter on the prototype, which is what
   * lets a 64-bit field be handed out as a `bigint`, and a getter is
   * invisible to `JSON.stringify` and to a shallow copy. So each of
   * these classes says what it holds when it is asked, and a caller
   * stringifying a row gets the node rather than `{}`. A `bigint`
   * still has no JSON spelling, so a caller doing that passes a
   * replacer, which they already had to.
   */
  toJSON(): object
}

/**
 * One edge of the graph.
 *
 * `ord` is where the edge's properties sit, which is its place in the
 * order the table was loaded in. That is what names an edge: a pair of
 * endpoints does not, since the same pair may run more than once and
 * each of those edges carries its own values. It is the field a caller
 * usually ignores and the one nothing else can replace.
 */
export declare class ZuRel {
  get table(): string
  get src(): bigint
  get dst(): bigint
  get ord(): bigint
  /**
   * The same thing as a plain object, for the reason [`ZuNode::to_json`]
   * gives.
   */
  toJSON(): object
}

/**
 * A time of day, as nanoseconds from midnight, with the offset from
 * UTC in minutes for a zoned one and `null` for a local one.
 *
 * The offset is minutes and never an IANA name, which is the engine's
 * decision and worth repeating here: a name is a rule that changes
 * under a stored value when the zone database is updated, and a value
 * that means something different tomorrow is not a value.
 */
export declare class ZuTime {
  offset?: number
  constructor(nanos: bigint, offset?: number | undefined | null)
  get nanos(): bigint
  /**
   * The same time as a `Temporal.PlainTime`.
   *
   * A local time only. A time with an offset has no `Temporal` type
   * at all, so one throws here rather than losing the offset, and the
   * message says why.
   */
  toTemporal(): ZuPlainTime
  /**
   * The same thing as a plain object, for the reason [`ZuNode::to_json`]
   * gives.
   */
  toJSON(): object
}

/**
 * A date and a time together, as nanoseconds from the epoch, with the
 * offset from UTC in minutes for a zoned one and `null` for a local
 * one.
 *
 * A zoned one holds the instant in UTC and the offset separately, so
 * two of them compare as instants while each still prints in the zone
 * it was written in.
 */
export declare class ZuTimestamp {
  offset?: number
  constructor(nanos: bigint, offset?: number | undefined | null)
  get nanos(): bigint
  /**
   * The same instant as a `Temporal.PlainDateTime` for a local one
   * and a `Temporal.ZonedDateTime` for a zoned one.
   *
   * The zone of a zoned one is the offset it was written at, spelled
   * `+02:00`, because that is what the engine stores. A named zone is
   * a rule that changes under a stored value when the zone database
   * is updated, so no value here has ever had one.
   */
  toTemporal(): ZuPlainDateTime | ZuZonedDateTime
  /**
   * The same thing as a plain object, for the reason [`ZuNode::to_json`]
   * gives.
   */
  toJSON(): object
}

/**
 * The revision of the C ABI this client implements the semantics of.
 *
 * Not the same number as [`version`] and not meant to be: the ABI is
 * the specification every zu client is graded against, so this is what
 * says which edition of that specification the behaviour here matches,
 * and it moves when the specification does rather than when this crate
 * does.
 */
export declare function abiVersion(): string

/**
 * Opens the database at `path` and connects to it.
 *
 * Creates one when the path holds nothing, which is what a first
 * program expects and what every embedded database does. A read-only
 * connection never creates anything.
 *
 * With no path, with `null`, or with `':memory:'`, the database is in
 * memory and no file is made anywhere. It is the whole engine and not
 * a reduced one, so it takes writes and transactions and the appender
 * exactly as a database on disk does, and it is gone when the last
 * connection to it is. Options may stand where the path would in that
 * case, so `connect({ threads: 2 })` is a call and not a mistake.
 */
export declare function connect(path?: string | ConnectOptions | undefined | null, options?: ConnectOptions | undefined | null): Promise<Connection>

/**
 * What a connection can be opened with.
 *
 * Every field is optional and every default is the engine's, because
 * a client that invents its own defaults is a client whose numbers
 * have to be found and changed twice.
 */
export interface ConnectOptions {
  /**
   * Opens without creating and refuses every statement that writes.
   * A read-only connection never creates a database, so a mistyped
   * path is an error here rather than an empty database.
   */
  readOnly?: boolean
  /** How much memory the executor may hold, in bytes. */
  memoryLimit?: bigint
  /** How many threads the executor may use. */
  threads?: number
  /**
   * How INT64 comes back, for every statement on this connection.
   * `bigint` unless it is said otherwise here, and a statement may
   * say otherwise again for itself.
   */
  bigIntMode?: ZuBigIntMode
  /**
   * Gives back `Temporal` values rather than this client's four
   * temporal classes, for every statement on this connection.
   *
   * Refused here, when the runtime has no `Temporal`, rather than at
   * the first row that happens to hold a date: a program that asked
   * for this and was quietly given something else would find out on
   * the one code path its tests did not cover. Node 26 and the
   * current browsers have `Temporal`, Node 24 has it behind
   * `--harmony-temporal`, and a program that cannot be sure of its
   * runtime uses `toTemporal()` on the value it wants instead.
   *
   * On the connection and not on a statement, because both spellings
   * are exact and a program picks the one it wants to read for as
   * long as it lives, where `bigIntMode` is a trade a single query
   * makes.
   *
   * A time with an offset keeps its class either way, because
   * `Temporal` has no type for one.
   */
  temporal?: boolean
}

/** Writes a new database at `path` and answers what went into it. */
export declare function load(path: string, options: ZuLoadOptions): Promise<ZuLoadStats>

/** The version of the client. */
export declare function version(): string