tricu

lib.js (6929B)

---

 /** Native tree calculus and IO via Haskell's C ABI. Roots are owned bigint IDs. */
 import { existsSync, realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import koffi from 'koffi';
 
 export function findLib() {
   if (process.env.TRICU_LIB) {
     if (!existsSync(process.env.TRICU_LIB)) throw new Error(`TRICU_LIB not found: ${process.env.TRICU_LIB}`);
     return realpathSync(process.env.TRICU_LIB);
   }
   const directory = dirname(fileURLToPath(import.meta.url));
   for (const name of ['libtricu-haskell.so', 'libtricu-haskell.dylib', 'tricu-haskell.dll']) {
     const candidate = join(directory, name);
     if (existsSync(candidate)) return realpathSync(candidate);
   }
   throw new Error('Set TRICU_LIB to the Haskell embedding library');
 }
 
 export class TricuError extends Error {
   constructor(status, message) {
     super(`tricu status ${status}: ${message}`);
     this.status = status;
   }
 }
 
 // One process-wide library, kept loaded for the lifetime of the process.
 let loaded;
 function native(path) {
   const resolved = realpathSync(path);
   if (loaded) {
     if (loaded.path !== resolved) throw new Error('One Haskell embedding library per process');
     return loaded.api;
   }
   const lib = koffi.load(resolved);
   const declarations = {
     init: 'void tricu_init(void)',
     abi_version: 'uint32_t tricu_abi_version(void)',
     context_new: 'uint32_t tricu_context_new(_Out_ uint64_t *out)',
     context_free: 'uint32_t tricu_context_free(uint64_t ctx)',
     release: 'uint32_t tricu_release(uint64_t ctx, uint64_t value)',
     buffer_free: 'void tricu_buffer_free(void *buffer)',
     run_io: 'uint32_t tricu_run_io(uint64_t ctx, uint64_t program, _Out_ uint32_t *outcome, _Out_ uint64_t *value, _Out_ uint64_t *cleanup)',
     load_bundle: 'uint32_t tricu_load_bundle(uint64_t ctx, const uint8_t *bytes, size_t len, const uint8_t *name, size_t name_len, _Out_ uint64_t *out)',
     last_error: 'uint32_t tricu_last_error(uint64_t ctx, _Out_ void **out, _Out_ size_t *len)',
   };
   for (const name of ['retain', 'stem', 'reduce']) declarations[name] =
     `uint32_t tricu_${name}(uint64_t ctx, uint64_t value, _Out_ uint64_t *out)`;
   for (const name of ['fork', 'apply']) declarations[name] =
     `uint32_t tricu_${name}(uint64_t ctx, uint64_t a, uint64_t b, _Out_ uint64_t *out)`;
   declarations.leaf = 'uint32_t tricu_leaf(uint64_t ctx, _Out_ uint64_t *out)';
   declarations.child = 'uint32_t tricu_child(uint64_t ctx, uint64_t value, uint32_t index, _Out_ uint64_t *out)';
   for (const name of ['kind', 'to_bool']) declarations[name] =
     `uint32_t tricu_${name}(uint64_t ctx, uint64_t value, _Out_ uint32_t *out)`;
   for (const name of ['from_u64', 'to_u64']) declarations[name] =
     `uint32_t tricu_${name}(uint64_t ctx, uint64_t value, _Out_ uint64_t *out)`;
   for (const name of ['bytes', 'utf8']) {
     declarations[`from_${name}`] = `uint32_t tricu_from_${name}(uint64_t ctx, const uint8_t *bytes, size_t len, _Out_ uint64_t *out)`;
     declarations[`to_${name}`] = `uint32_t tricu_to_${name}(uint64_t ctx, uint64_t value, _Out_ void **out, _Out_ size_t *len)`;
   }
   const api = Object.fromEntries(Object.entries(declarations).map(([name, declaration]) => [name, lib.func(declaration)]));
   api.init();
   if (api.abi_version() !== 1) throw new Error('Haskell embedding ABI 1 required');
   loaded = { path: resolved, lib, api };
   return api;
 }
 
 export class Library {
   constructor(path = findLib()) { this.api = native(path); }
   context() { return new Context(this); }
 }
 
 export class Context {
   constructor(library) {
     this.api = library.api;
     const out = [0n];
     const status = this.api.context_new(out);
     if (status) throw new TricuError(status, 'creating context');
     this.identity = BigInt(out[0]);
   }
   _copy(pointer, length) {
     try { return Buffer.from(koffi.decode(pointer, 'uint8_t', Number(length))); }
     finally { this.api.buffer_free(pointer); }
   }
   _check(status) {
     if (!status) return;
     const pointer = [null], length = [0];
     const diagnostic = this.api.last_error(this.identity, pointer, length);
     const message = diagnostic ? 'invalid context' : this._copy(pointer[0], length[0]).toString('utf8');
     throw new TricuError(status, message);
   }
   _out(name, ...args) {
     const out = [0n];
     this._check(this.api[name](this.identity, ...args, out));
     return BigInt(out[0]);
   }
   close() {
     if (this.identity !== 0n) {
       this._check(this.api.context_free(this.identity));
       this.identity = 0n;
     }
   }
   [Symbol.dispose]() { this.close(); }
   release(value) { this._check(this.api.release(this.identity, value)); }
   retain(value) { return this._out('retain', value); }
   leaf() { return this._out('leaf'); }
   stem(value) { return this._out('stem', value); }
   fork(a, b) { return this._out('fork', a, b); }
   apply(fn, arg) { return this._out('apply', fn, arg); }
   reduce(value) { return this._out('reduce', value); }
   child(value, index) {
     if (!Number.isInteger(index) || index < 0 || index > 0xffffffff) throw new RangeError('invalid child index');
     return this._out('child', value, index);
   }
   kind(value) { return Number(this._out('kind', value)); }
   number(value) {
     if (typeof value === 'number' && !Number.isSafeInteger(value)) throw new RangeError('use bigint for large integers');
     const integer = BigInt(value);
     if (integer < 0n || integer > 0xffffffffffffffffn) throw new RangeError('number must fit uint64');
     return this._out('from_u64', integer);
   }
   toNumber(value) { return this._out('to_u64', value); }
   toBool(value) { return this._out('to_bool', value) !== 0n; }
   bytes(value) {
     const bytes = Buffer.from(value);
     return this._out('from_bytes', bytes, bytes.length);
   }
   string(value) {
     // Buffer UTF-8 encoding otherwise silently replaces unpaired surrogates.
     if (!value.isWellFormed()) throw new TypeError('string contains an unpaired surrogate');
     const bytes = Buffer.from(value, 'utf8');
     return this._out('from_utf8', bytes, bytes.length);
   }
   _buffer(name, value) {
     const pointer = [null], length = [0];
     this._check(this.api[name](this.identity, value, pointer, length));
     return this._copy(pointer[0], length[0]);
   }
   toBytes(value) { return this._buffer('to_bytes', value); }
   toString(value) { return this._buffer('to_utf8', value).toString('utf8'); }
   loadBundle(value, name) {
     if (!name.isWellFormed()) throw new TypeError('invalid export name');
     const bytes = Buffer.from(value), encoded = Buffer.from(name, 'utf8');
     return this._out('load_bundle', bytes, bytes.length, encoded, encoded.length);
   }
   runIO(program) {
     const outcome = [0], value = [0n], cleanup = [0n];
     this._check(this.api.run_io(this.identity, program, outcome, value, cleanup));
     return { outcome: outcome[0], value: BigInt(value[0]), cleanup: BigInt(cleanup[0]) };
   }
 }