yggdryl 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -1,30 +1,267 @@
-# yggdryl (Node.js)
+# Yggdryl for JavaScript
 
-Node.js bindings for [**yggdryl**](https://github.com/Platob/yggdryl), backed by
-the Rust `yggdryl` core crate (via [napi-rs](https://napi.rs)).
+```javascript
+const { json, toml, yaml } = require('yggdryl')
+
+const bytes = json.dumps({ symbol: 'AAPL', price: 224.62 })
+const trade = json.loads(bytes)
+const config = toml.loads('symbol = "AAPL"\nprice = 224.62\n')
+const documents = yaml.loadsAll(Buffer.from('---\nsymbol: AAPL\n---\nsymbol: MSFT\n'))
+
+console.assert(Buffer.isBuffer(bytes))
+console.assert(trade.symbol === 'AAPL')
+console.assert(config.symbol === 'AAPL')
+console.assert(documents[1].symbol === 'MSFT')
+```
+
+JSON, YAML, and TOML APIs are byte-first and preserve binary
+values, large integers, dates, maps, sets, and typed arrays. `load` and `dump`
+also accept paths, descriptors, file URLs, and Node or WHATWG streams. Primitive
+strings are content unless they name an existing regular file; `loads` always
+treats them as content. Real paths redirect to Rust reader/writer methods
+without a whole-file JavaScript buffer. Stream overloads are asynchronous and
+apply writable backpressure without closing caller-owned I/O.
+
+```javascript
+const { Readable, Writable } = require('node:stream')
+const { json } = require('yggdryl')
+
+async function main() {
+  const value = await json.load(Readable.from(['{"id":', '42}']))
+  await json.dump(value, new Writable({
+    write(chunk, _encoding, done) {
+      process.stdout.write(chunk, done)
+    },
+  }))
+}
+
+main()
+```
+
+`loadAll` redirects an async byte source to the lazy `loadAllStream` iterator;
+`dumpAll` redirects a writable destination to `dumpAllStream`. Single-document
+stream reads use one bounded buffer because Node's async reader cannot be
+passed to synchronous Rust `Read`; multi-document reads and writes stay
+incremental. Buffer, ArrayBuffer, SharedArrayBuffer, DataView, and typed-array
+offsets are all preserved exactly.
+
+TOML is deliberately single-document and exposes only `loads`, `load`,
+`dumps`, `dump`, `loadStream`, and `dumpStream`. Generic `codec` operations
+infer `.toml` paths in Rust or accept explicit `format: 'toml'` for content.
+
+```javascript
+const { DataType, Field, MediaType, MimeType, Uri } = require('yggdryl')
+
+const type = DataType.fromString('struct<symbol:string,price:decimal(18,4)>')
+const coarseClock = DataType.time('milliseconds')
+const preciseClock = DataType.time('nanoseconds')
+const field = new Field('trade', type, false, { source: 'book' })
+field.setTableName('trades')
+field.setParquetFieldId(17)
+field.setLocation('s3://warehouse/trades/data.arrow')
+field.setProperty('postgres', 'type', 'jsonb')
+const file = Uri.fromPath('C:\\data\\trades.arrow')
+const encoded = Uri.fromString('https://example.test/trades.csv.gz')
+
+console.assert(Field.fromString(field.toString()).equals(field))
+console.assert(coarseClock.kind === 'time32')
+console.assert(preciseClock.kind === 'time64')
+console.assert(field.parquetFieldId === 17)
+console.assert(field.get('PARQUET:field_id') === '17')
+console.assert(field.location.scheme === 's3')
+console.assert(field.getProperty('postgres', 'type') === 'jsonb')
+console.assert(file.toString() === 'file:///C:/data/trades.arrow')
+console.assert(file.toPath() === 'C:/data/trades.arrow')
+console.assert(encoded.mediaType.base.equals(MimeType.fromString('text/csv')))
+encoded.setMediaType(MediaType.fromParts('application/json', ['application/gzip']))
+console.assert(encoded.fileName === 'trades.json.gz')
+```
+
+The Node-API package exposes native `DataType`, `Field`, `IOBase`, `MimeType`,
+`MediaType`, `Timezone`, `Uri`, `Url`, `Urn`, and `Value` values, the record pair
+`BatchReader` and `RecordOptions`, and the `iceberg` namespace over all of them.
+Recursive parsing, validation, Arrow casting, record scalar conversion, codec
+conversion, ordering, stable hashing, metadata, and path normalization stay in
+Rust.
+`DataType.time(unit)` and `fields.time(name, unit)` require an explicit unit;
+seconds/milliseconds select Time32 and microseconds/nanoseconds select Time64.
+They accept the same native unit aliases as datatype parsing and reject
+interval layouts.
+
+```javascript
+const { Record, fields } = require('yggdryl')
+
+const Trade = Record.define('Trade', [
+  fields.int64('id'),
+  fields.utf8('symbol'),
+  fields.decimal128('price', 18, 4),
+])
+const rows = [
+  new Trade({ id: 1n, symbol: 'AAPL', price: 2246200n }),
+  new Trade({ id: 2n, symbol: 'MSFT', price: 4187900n }),
+]
+
+const batch = Trade.intoArrowRecordBatch(rows)
+const restored = [...Trade.fromArrowRecordBatch(batch)]
+
+console.assert(restored[0].symbol === 'AAPL')
+console.assert(restored[1].price === 4187900n)
+```
+
+Each defined class owns one shared native Record schema/name index. Apache
+Arrow JS conversion is an explicit copied IPC boundary: it never serializes per
+property access and does not claim zero-copy C Data interoperability. Use
+`intoArrowRecordBatches` for bounded output, `fromArrowRecordBatchReader` for
+batch-bounded input, and `intoArrowIPC`/`fromArrowIPC` for every physical layout
+representable by the core `yggdryl::arrow` IPC runtime. The Apache Arrow
+dependency loads only when an Arrow adapter is used.
+
+`DataType.castArrowArray`, `Field.castArrowArray`, `DataType.castArrowBatch`,
+and `Field.castArrowBatch` route copied Apache Arrow JS holders through the one
+native `yggdryl::arrow` cast engine. Exact no-op casts preserve the original
+Vector or RecordBatch identity; changed outputs follow `{safe: true}` by
+default and never use a JavaScript conversion table.
+
+Tabular cursor reads validate the declared source schema before any optional
+target projection. Getters use a non-consuming snapshot. Overwrite, append,
+indexed set, and positional upsert compute a complete validated replacement
+before invoking one private atomic overwrite-all hook. `overwriteRecords`,
+`appendRecords`, and `upsertRecords` provide the matching class-bound bulk
+helpers and validate their options and source-to-backend cast plan before
+consuming a one-shot row iterable. Dataset iterables likewise stop at their
+first incompatible batch. Numeric selectors and matching table URLs with a
+`#N` fragment address a batch; the exact table URL addresses the whole resource.
+Tabular and dataset schema getters retain a stable canonical Arrow JS identity
+and fingerprint-repair caller mutation from native state before reuse.
+
+Run `npm run bench:record` or `npm run bench:tabular` to measure native Record
+behavior and the copied-IPC read, cast, overwrite, indexed mutation, in-memory
+table, and dataset paths separately. Set `YGGDRYL_BENCH_ITERATIONS` to change the
+default sample count.
+
+```javascript
+const { Record, fields } = require('yggdryl')
 
-## Build
+const payload = fields.struct('payload', [
+  fields.int64('count'),
+  fields.utf8('note', { nullable: true }),
+])
+const value = payload.defaultJSValue()
 
-```bash
-npm install
-npm run build            # napi build --platform --release
-npm test                 # node --test
+console.assert(value instanceof Record)
+console.assert(value.count === 0n && value.note === null)
+console.assert(payload.defaultJSHint().constructor instanceof Function)
+console.assert(fields.int32('id').defaultArrowScalar() === 0)
+console.assert(
+  fields.uint8('small').toSchemeCompat('spark').dataType.kind === 'int16',
+)
 ```
 
-## Usage
+Defaults are computed by the Rust core and projected through the same typed
+path as Record values. Struct defaults remain schema-bound native Records;
+runtime hints use a bounded native constructor category, are frozen and
+cached, and do not materialize a default value or exact Field schema.
+For a Struct Field, that metadata-free hint constructor is a logical layout
+hint through the generic `Record` class, so nested metadata is not exposed by
+the hint. The exact default Record still retains its complete outer Field and
+uses its own generated class. Hint identity is wrapper-local, not a global
+interning promise for equivalent schemas.
+Arrow scalars use one copied one-row IPC projection into Apache Arrow JS, and
+unsupported Arrow JS layouts fail without introducing a second scalar model.
+Run `npm run bench:defaults` for JavaScript defaults, cached hints,
+compatibility normalization, and Arrow-scalar IPC materialization.
 
 ```javascript
-const { Uri, Url } = require('yggdryl')
+const { Field, MediaType, MimeType } = require('yggdryl')
 
-const uri = new Uri('urn:isbn:0451450523')
-console.log(uri.scheme)        // urn
-console.log(uri.path)          // isbn:0451450523
+const media = MediaType.fromParts(
+  MimeType.CSV,
+  new Set([MimeType.GZIP, MimeType.ZSTD]),
+)
+const field = new Field('payload', 'binary', false, {
+  'HTTPS:Content-Type': 'text/csv; charset=utf-8',
+})
+field.setMediaType(media)
 
-const url = new Url('https://user:pw@example.com:8443/api?v=1#top')
-console.log(url.host)          // example.com
-console.log(url.port)          // 8443
-console.log(url.username)      // user
-console.log(url.toString())    // https://user:pw@example.com:8443/api?v=1#top
+console.assert(field.mimeType.equals(MimeType.CSV))
+console.assert(field.contentEncoding === 'gzip, zstd')
+console.assert(field.get('HTTPS:CONTENT-TYPE') === 'text/csv')
 ```
 
-Invalid input throws.
+`MimeType` exposes every native known value as a frozen class constant and
+accepts custom validated MIME names. `MediaType()` defaults to octet-stream;
+its iterable adapters consume once and `encodings` returns a detached Array.
+HTTP and HTTPS Field input shares canonical lowercase `http:*` Arrow metadata.
+Raw headers preserve parameters, while typed MIME/media, exact unsigned
+content length (`bigint`), and absolute HTTP Location accessors remain native.
+Media pair updates are atomic and cache-aware.
+
+```javascript
+const { DataType, Field, fields } = require('yggdryl')
+
+const id = fields.int32('id', { nullable: false })
+const tags = fields.list('tags', fields.utf8('item'))
+const row = DataType.fromFields([id, tags])
+
+console.assert(id instanceof Field)
+console.assert(tags.dataType.kind === 'list')
+console.assert(row.kind === 'struct')
+console.assert(id.showDiff(id) === '✓ equal')
+console.assert([...id.showDiffs(fields.int64('id'))].length > 0)
+```
+
+The `fields` namespace covers every datatype variant and returns the same
+generic native `Field`; TypeScript retains the exact kind/value view. Equality
+can ignore recursive metadata with `equals(other, false)`, while `showDiffs`
+returns a UTF-8 iterator and `showDiff` joins its terminal-readable lines.
+
+Finite alternatives can use `DataType.variant(fields)` or
+`fields.variant(name, fields, options)`. Both assign dense Arrow Union type IDs
+in declaration order and retain the ordinary `union` kind; Record values use
+the explicit `{ typeId, value }` shape. Iceberg/Parquet Variant and PostgreSQL
+`json/jsonb` remain explicit adapter formats, not aliases for this tagged Arrow
+layout.
+
+```javascript
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const arrow = require('apache-arrow')
+const { BatchReader, Field, IOBase, fields, iceberg } = require('yggdryl')
+
+// A location is absolute: a handle is a URL, and a relative name names no root.
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'yggdryl-'))
+
+const schema = iceberg.assignFieldIds(
+  fields.struct('row', [Field.from('id: int64'), Field.from('venue: utf8')], {
+    nullable: false,
+  }),
+)
+const rows = new arrow.Table({
+  id: arrow.vectorFromArray([1n, 2n], new arrow.Int64()),
+  venue: arrow.vectorFromArray(['XNAS', 'XNYS'], new arrow.Utf8()),
+})
+
+// A handle reads and writes records through the encoding its name declares.
+const file = new IOBase(path.join(root, 'trades.parquet'))
+file.writeArrowBatchReader(BatchReader.from(rows))
+console.assert(file.readArrowBatchReader().toTable().numRows === 2)
+
+// An Iceberg table is a folder, and a folder is all it ever touches.
+const table = iceberg.Table.create(path.join(root, 'trades'), schema, ['venue'])
+table.append(rows)
+console.assert(table.currentSnapshot.operation === 'append')
+console.assert(table.dataFiles().length === 2)
+```
+
+`BatchReader` is the one record shape: a read returns one, a write consumes one,
+and each batch crosses as its own Apache Arrow IPC stream, because Arrow JS has
+no C Data consumer. `BatchReader.from` accepts another reader, an Arrow JS
+`Table` or `RecordBatch`, an array of batches, or Arrow IPC bytes. The encoding
+is never an argument: `recordOptions()` derives it from the handle's media type,
+covering Arrow IPC and Apache Parquet.
+
+Use the complete [JavaScript guide](https://platob.github.io/yggdryl/extensions/javascript/)
+for schema and identifier APIs, the [Record and Arrow guide](https://platob.github.io/yggdryl/extensions/javascript/records/)
+for typed rows and copied IPC interoperability, and the [codec guide](https://platob.github.io/yggdryl/extensions/javascript/codecs/)
+for safe class registries, generic format inference, and streaming.

package/benchmarks/codec.js

@@ -0,0 +1,133 @@
+'use strict'
+
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { performance } = require('node:perf_hooks')
+const { Readable, Writable } = require('node:stream')
+const { Value, codec, json, toml, yaml } = require('yggdryl')
+
+const value = {
+  trades: Array.from({ length: 1_000 }, (_, index) => ({
+    id: BigInt(index),
+    price: index / 100,
+    symbol: `SYM${index % 20}`,
+  })),
+}
+const exotic = {
+  bytes: Buffer.from([0, 1, 127, 255]),
+  map: new Map([[{ venue: 'XPAR' }, new Set([1n, 2n])]]),
+  nan: Number.NaN,
+  regexp: /a\/b/giu,
+  typed: new Uint16Array([0, 65535]),
+}
+// The temporal and decimal boundary is its own cost: each value crosses as
+// parts rather than as one number, and a Date is rebuilt on the way back.
+const temporal = {
+  at: Value.timestamp(1700000000000000n, 'us', 'UTC'),
+  date: new Date('2026-08-15T12:30:00.000Z'),
+  on: Value.date(19723),
+  price: Value.decimal(-1050n, 2),
+  sinceMidnight: Value.time(45296000000n, 'us'),
+  took: Value.duration(90n, 's'),
+}
+let deep = { leaf: true }
+for (let depth = 0; depth < 24; depth += 1) deep = { nested: deep }
+
+function measure(name, bytes, iterations, operation) {
+  for (let index = 0; index < 5; index += 1) operation()
+  const started = performance.now()
+  for (let index = 0; index < iterations; index += 1) operation()
+  const elapsed = performance.now() - started
+  const throughput = (bytes * iterations) / (elapsed / 1_000) / (1024 * 1024)
+  console.log(
+    `${name}: ${(elapsed / iterations).toFixed(3)} ms/op, ${throughput.toFixed(1)} MiB/s`,
+  )
+}
+
+async function measureAsync(name, bytes, iterations, operation) {
+  for (let index = 0; index < 2; index += 1) await operation()
+  const started = performance.now()
+  for (let index = 0; index < iterations; index += 1) await operation()
+  const elapsed = performance.now() - started
+  const throughput = (bytes * iterations) / (elapsed / 1_000) / (1024 * 1024)
+  console.log(
+    `${name}: ${(elapsed / iterations).toFixed(3)} ms/op, ${throughput.toFixed(1)} MiB/s`,
+  )
+}
+
+async function main() {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'yggdryl-node-bench-'))
+  try {
+    for (const [name, format, extension] of [
+      ['json', json, 'json'],
+      ['toml', toml, 'toml'],
+      ['yaml', yaml, 'yaml'],
+    ]) {
+      const encoded = format.dumps(value)
+      const text = encoded.toString('utf8')
+      const padded = Buffer.concat([Buffer.from('xx'), encoded, Buffer.from('yy')])
+      const view = new DataView(
+        padded.buffer,
+        padded.byteOffset + 2,
+        encoded.byteLength,
+      )
+      const file = path.join(directory, `value.${extension}`)
+      fs.writeFileSync(file, encoded)
+
+      // Keep these group spellings stable so before/after runs remain comparable.
+      measure(`${name}/slice`, encoded.length, 100, () => format.loads(encoded))
+      measure(`${name}/string`, encoded.length, 100, () => format.loads(text))
+      measure(`${name}/offset_view`, encoded.length, 100, () => format.loads(view))
+      measure(`${name}/reader_path`, encoded.length, 100, () => format.load(file))
+      measure(`${name}/vector_emit`, encoded.length, 100, () => format.dumps(value))
+      measure(`${name}/writer_path`, encoded.length, 100, () => format.dump(value, file))
+      await measureAsync(`${name}/reader_stream`, encoded.length, 25, () =>
+        format.load(Readable.from([encoded])),
+      )
+      await measureAsync(`${name}/writer_stream`, encoded.length, 25, () =>
+        format.dump(
+          value,
+          new Writable({ write(_chunk, _encoding, done) { done() } }),
+        ),
+      )
+
+      const exoticEncoded = format.dumps(exotic)
+      measure(`${name}/exotic_values`, exoticEncoded.length, 50, () =>
+        format.loads(exoticEncoded),
+      )
+      const temporalEncoded = format.dumps(temporal)
+      measure(`${name}/temporal_values`, temporalEncoded.length, 50, () =>
+        format.loads(temporalEncoded),
+      )
+      const deepEncoded = format.dumps(deep)
+      measure(`${name}/deep_nested`, deepEncoded.length, 50, () =>
+        format.loads(deepEncoded),
+      )
+    }
+
+    // The pivot is the conversion every load and dump crosses, measured on its
+    // own against the same payload so a codec number can be read against it.
+    const pivotBytes = json.dumps(value).length
+    measure('pivot/from_js', pivotBytes, 100, () => Value.fromJs(value))
+    const pivot = Value.fromJs(value)
+    measure('pivot/as_js', pivotBytes, 100, () => pivot.asJs())
+
+    const inferred = json.dumps(value)
+    measure('generic/content_sniff', inferred.length, 100, () => codec.from(inferred))
+    measure('generic/explicit_json', inferred.length, 100, () =>
+      codec.from(inferred, { format: 'json' }),
+    )
+    const inferredToml = toml.dumps(value)
+    measure('generic/content_infer_toml', inferredToml.length, 50, () =>
+      codec.from(inferredToml),
+    )
+  } finally {
+    fs.rmSync(directory, { force: true, recursive: true })
+  }
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})