@sanbus/galley-core 0.0.1

package/dist/constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Constants mirroring `bindings/c/galley.h` status and kind enumerations.
+ * These are the single source for JavaScript consumers; they must stay
+ * in sync with the C header.
+ */
+export declare const INVALID_NODE = 18446744073709551615n;
+export declare const STATUS_OK = 0;
+export declare const STATUS_ERROR_NULL_ARGUMENT = -1;
+export declare const STATUS_ERROR_SYNTAX = -2;
+export declare const STATUS_ERROR_INDENTATION = -3;
+export declare const STATUS_ERROR_STACK_OVERFLOW = -4;
+export declare const STATUS_ERROR_AST_CAPACITY_EXCEEDED = -5;
+export declare const STATUS_ERROR_UNTERMINATED_RAW_STRING = -6;
+export declare const STATUS_ERROR_OUT_OF_MEMORY = -7;
+export declare const STATUS_ERROR_INTERNAL = -8;
+export declare const STATUS_ERROR_NO_DIAGNOSTIC = -9;
+export declare const STATUS_ERROR_INVALID_NODE = -10;
+export declare const STATUS_ERROR_IO = -11;
+export declare const STATUS_ERROR_SEMANTIC = -12;
+export declare const PARSER_TYPE_LL = 0;
+export declare const PARSER_TYPE_LR = 1;
+export declare const RECOVERY_MODE_DISABLED = 0;
+export declare const RECOVERY_MODE_AUTOMATIC = 1;
+export declare const RECOVERY_MODE_EXPLICIT = 2;
+export declare const KIND_NONE = 0;
+export declare const KIND_SYNTAX = 1;
+export declare const KIND_INDENTATION = 2;
+export declare const KIND_SEMANTIC = 3;
+export declare const RECOVERY_TARGET_NONE = 0;
+export declare const RECOVERY_TARGET_LHS_VARIABLE = 1;
+export declare const RECOVERY_TARGET_PRODUCTION = 2;
+export declare const RECOVERY_TARGET_OCCURRENCE = 3;
+export declare const RESUME_BEFORE = 0;
+export declare const RESUME_AFTER = 1;

package/dist/constants.js

@@ -0,0 +1,41 @@
+/**
+ * Constants mirroring `bindings/c/galley.h` status and kind enumerations.
+ * These are the single source for JavaScript consumers; they must stay
+ * in sync with the C header.
+ */
+export const INVALID_NODE = 0xffffffffffffffffn; // 2^64-1
+// Status codes (negative = failure)
+export const STATUS_OK = 0;
+export const STATUS_ERROR_NULL_ARGUMENT = -1;
+export const STATUS_ERROR_SYNTAX = -2;
+export const STATUS_ERROR_INDENTATION = -3;
+export const STATUS_ERROR_STACK_OVERFLOW = -4;
+export const STATUS_ERROR_AST_CAPACITY_EXCEEDED = -5;
+export const STATUS_ERROR_UNTERMINATED_RAW_STRING = -6;
+export const STATUS_ERROR_OUT_OF_MEMORY = -7;
+export const STATUS_ERROR_INTERNAL = -8;
+export const STATUS_ERROR_NO_DIAGNOSTIC = -9;
+export const STATUS_ERROR_INVALID_NODE = -10;
+export const STATUS_ERROR_IO = -11;
+export const STATUS_ERROR_SEMANTIC = -12;
+// Parser families
+export const PARSER_TYPE_LL = 0;
+export const PARSER_TYPE_LR = 1;
+// Recovery modes
+export const RECOVERY_MODE_DISABLED = 0;
+export const RECOVERY_MODE_AUTOMATIC = 1;
+export const RECOVERY_MODE_EXPLICIT = 2;
+// Diagnostic kinds
+export const KIND_NONE = 0;
+export const KIND_SYNTAX = 1;
+export const KIND_INDENTATION = 2;
+export const KIND_SEMANTIC = 3;
+// Recovery targets
+export const RECOVERY_TARGET_NONE = 0;
+export const RECOVERY_TARGET_LHS_VARIABLE = 1;
+export const RECOVERY_TARGET_PRODUCTION = 2;
+export const RECOVERY_TARGET_OCCURRENCE = 3;
+// Resume sides
+export const RESUME_BEFORE = 0;
+export const RESUME_AFTER = 1;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC,CAAC,SAAS;AAE1D,oCAAoC;AACpC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAC3B,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,CAAC;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,CAAC;AACtC,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,CAAC;AAC3C,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC,CAAC;AACrD,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC,CAAC;AACvD,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,CAAC;AAC7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,CAAC;AACxC,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,CAAC;AAC7C,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,EAAE,CAAC;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAE,CAAC;AACnC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,EAAE,CAAC;AAEzC,kBAAkB;AAClB,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAChC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,iBAAiB;AACjB,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACxC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC,mBAAmB;AACnB,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAC3B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAClC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAE/B,mBAAmB;AACnB,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AACtC,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAC5C,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAE5C,eAAe;AACf,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAC/B,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC"}

package/dist/diagnostic.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Read-only snapshot of a parse diagnostic.
+ * All `Uint8Array` fields are copies that remain valid after the next parse.
+ */
+/**
+ * Display name for the synthetic control-byte terminals (end of input and
+ * the indentation pair), which never occur as user-typable input. Exact
+ * full-token match only; anything else returns null and the caller keeps
+ * its existing rendering.
+ *
+ * Mirrors `tokenDisplayName` in `src/runtime/string.zig` until the general
+ * per-grammar mechanism arrives; keep the two tables in sync.
+ */
+export declare function displayTokenName(token: Uint8Array): string | null;
+export interface Diagnostic {
+    kind: number;
+    line: number;
+    column: number;
+    message: string;
+    messageAnsi: string;
+    unexpectedToken: Uint8Array | null;
+    expectedTokens: Uint8Array[];
+    context: string[];
+    syntaxErrorCount: number;
+    semanticErrorCount: number;
+    semantic: [string, string] | null;
+    indentation: [number, number] | null;
+    recoveryKind: number | null;
+    recoveryTerminal: Uint8Array | null;
+    recoveryResume: number | null;
+    recoveryLhsVariable: string | null;
+    recoveryProduction: [string, number] | null;
+    recoveryOccurrence: [string, number, number, string] | null;
+}

package/dist/diagnostic.js

@@ -0,0 +1,28 @@
+/**
+ * Read-only snapshot of a parse diagnostic.
+ * All `Uint8Array` fields are copies that remain valid after the next parse.
+ */
+/**
+ * Display name for the synthetic control-byte terminals (end of input and
+ * the indentation pair), which never occur as user-typable input. Exact
+ * full-token match only; anything else returns null and the caller keeps
+ * its existing rendering.
+ *
+ * Mirrors `tokenDisplayName` in `src/runtime/string.zig` until the general
+ * per-grammar mechanism arrives; keep the two tables in sync.
+ */
+export function displayTokenName(token) {
+    if (token.length !== 1)
+        return null;
+    switch (token[0]) {
+        case 0x00:
+            return "End of input";
+        case 0x01:
+            return "Indent";
+        case 0x02:
+            return "Dedent";
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=diagnostic.js.map

package/dist/diagnostic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.js","sourceRoot":"","sources":["../src/diagnostic.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,QAAQ,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACjB,KAAK,IAAI;YACP,OAAO,cAAc,CAAC;QACxB,KAAK,IAAI;YACP,OAAO,QAAQ,CAAC;QAClB,KAAK,IAAI;YACP,OAAO,QAAQ,CAAC;QAClB;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+import type { Diagnostic } from "./diagnostic.ts";
+/**
+ * Failure reported by a Galley operation.
+ * Mirrors Python's `galley.Error` (code + diagnostic snapshot).
+ */
+export declare class GalleyError extends Error {
+    readonly code: number;
+    readonly diagnostic: Diagnostic | null;
+    constructor(message: string, code: number, diagnostic?: Diagnostic | null);
+}
+/**
+ * The parser artifact a binding was told to load is not where it was told.
+ * Thrown by every adapter's artifact resolution instead of searching
+ * elsewhere. The universal loader catches exactly this class to try the
+ * next engine; anything else propagates loudly.
+ */
+export declare class MissingArtifactError extends Error {
+    readonly code = "galley:missing-artifact";
+    constructor(detail: string, buildHint: string);
+    /** True for missing-artifact failures even across duplicated installs. */
+    static is(error: unknown): error is MissingArtifactError;
+}

package/dist/errors.js

@@ -0,0 +1,38 @@
+/**
+ * Failure reported by a Galley operation.
+ * Mirrors Python's `galley.Error` (code + diagnostic snapshot).
+ */
+export class GalleyError extends Error {
+    code;
+    diagnostic;
+    constructor(message, code, diagnostic = null) {
+        super(message);
+        this.name = "GalleyError";
+        this.code = code;
+        this.diagnostic = diagnostic;
+    }
+}
+const MISSING_ARTIFACT_CODE = "galley:missing-artifact";
+/**
+ * The parser artifact a binding was told to load is not where it was told.
+ * Thrown by every adapter's artifact resolution instead of searching
+ * elsewhere. The universal loader catches exactly this class to try the
+ * next engine; anything else propagates loudly.
+ */
+export class MissingArtifactError extends Error {
+    code = MISSING_ARTIFACT_CODE;
+    constructor(detail, buildHint) {
+        super(`galley: parser artifact not found: ${detail}.\n${buildHint}`);
+        this.name = "MissingArtifactError";
+    }
+    /** True for missing-artifact failures even across duplicated installs. */
+    static is(error) {
+        if (error instanceof MissingArtifactError)
+            return true;
+        return (typeof error === "object" &&
+            error !== null &&
+            error.name === "MissingArtifactError" &&
+            error.code === MISSING_ARTIFACT_CODE);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAS;IACb,UAAU,CAAoB;IAEvC,YACE,OAAe,EACf,IAAY,EACZ,UAAU,GAAsB,IAAI;QAEpC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,qBAAqB,CAAC;IAEtC,YAAY,MAAc,EAAE,SAAiB;QAC3C,KAAK,CAAC,sCAAsC,MAAM,MAAM,SAAS,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;IAED,0EAA0E;IAC1E,MAAM,CAAC,EAAE,CAAC,KAAc;QACtB,IAAI,KAAK,YAAY,oBAAoB;YAAE,OAAO,IAAI,CAAC;QACvD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACb,KAA4B,CAAC,IAAI,KAAK,sBAAsB;YAC5D,KAA4B,CAAC,IAAI,KAAK,qBAAqB,CAC7D,CAAC;IACJ,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Galley JavaScript core — runtime-neutral public surface.
+ *
+ * Each adapter package (`@sanbus/galley-node`, `@sanbus/galley-bun`, `@sanbus/galley-deno`)
+ * binds these classes to its {@link FfiPort} and re-exports them.
+ */
+import { Session, Walker } from "./session.ts";
+import type { SessionOptions, WalkStep } from "./session.ts";
+import { Node } from "./node.ts";
+import { GalleyError, MissingArtifactError } from "./errors.ts";
+import { resolveArtifact, artifactFileName, wasmArtifactFileName } from "./artifact.ts";
+import type { ArtifactHost } from "./artifact.ts";
+import type { Diagnostic } from "./diagnostic.ts";
+import { displayTokenName } from "./diagnostic.ts";
+import type { FfiPort, Handle, SessionCOptions, TreeSnapshot, WalkedStep, DispatchHandler } from "./port.ts";
+import { installProcedure, installProcedures, clearProcedures, listProcedures, ProcedureArguments, dispatchProcedure, setParsingSession, getParsingSession } from "./procedures.ts";
+import type { HookFn } from "./procedures.ts";
+import { encodeUtf8, decodeUtf8, byteLengthUtf8 } from "./text.ts";
+export { Session, Walker, Node, GalleyError, MissingArtifactError, resolveArtifact, artifactFileName, wasmArtifactFileName, displayTokenName, ProcedureArguments, installProcedure, installProcedures, clearProcedures, listProcedures, dispatchProcedure, setParsingSession, getParsingSession, encodeUtf8, decodeUtf8, byteLengthUtf8, };
+export type { Diagnostic, WalkStep, SessionOptions, FfiPort, Handle, SessionCOptions, TreeSnapshot, WalkedStep, DispatchHandler, HookFn, ArtifactHost };
+export * from "./constants.ts";

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * Galley JavaScript core — runtime-neutral public surface.
+ *
+ * Each adapter package (`@sanbus/galley-node`, `@sanbus/galley-bun`, `@sanbus/galley-deno`)
+ * binds these classes to its {@link FfiPort} and re-exports them.
+ */
+import { Session, Walker } from "./session.js";
+import { Node } from "./node.js";
+import { GalleyError, MissingArtifactError } from "./errors.js";
+import { resolveArtifact, artifactFileName, wasmArtifactFileName } from "./artifact.js";
+import { displayTokenName } from "./diagnostic.js";
+import { installProcedure, installProcedures, clearProcedures, listProcedures, ProcedureArguments, dispatchProcedure, setParsingSession, getParsingSession, } from "./procedures.js";
+import { encodeUtf8, decodeUtf8, byteLengthUtf8 } from "./text.js";
+export { Session, Walker, Node, GalleyError, MissingArtifactError, resolveArtifact, artifactFileName, wasmArtifactFileName, displayTokenName, ProcedureArguments, installProcedure, installProcedures, clearProcedures, listProcedures, dispatchProcedure, setParsingSession, getParsingSession, encodeUtf8, decodeUtf8, byteLengthUtf8, };
+export * from "./constants.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEnE,OAAO,EACL,OAAO,EACP,MAAM,EACN,IAAI,EACJ,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,cAAc,GACf,CAAC;AAEF,cAAc,gBAAgB,CAAC"}

package/dist/names.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared library filename mapping for every JavaScript adapter.
+ * One library name per platform: `lib<base>.dylib` on macOS, `<base>.dll`
+ * on Windows (no `lib` prefix), `lib<base>.so` elsewhere. The platform
+ * string comes from the host (`process.platform` under Node/Bun, where
+ * Windows reports `win32`; `Deno.build.os`, where it reports `windows`);
+ * both spellings map to the Windows name here so the adapters cannot
+ * diverge.
+ *
+ * This file imports nothing, on purpose: strict-mode Deno consumers
+ * (notably `deno/build.ts`) import it directly, and any cross-file import
+ * with a `.js` suffix breaks Deno's strict resolution. Runtime code takes
+ * these through `artifact.ts`; nothing takes them the other way.
+ */
+export declare function artifactFileName(base: string, platform: string): string;
+/**
+ * Shared wasm artifact filename. WebAssembly modules are platform-neutral:
+ * always `lib<base>.wasm`.
+ */
+export declare function wasmArtifactFileName(base: string): string;

package/dist/names.js

@@ -0,0 +1,29 @@
+/**
+ * Shared library filename mapping for every JavaScript adapter.
+ * One library name per platform: `lib<base>.dylib` on macOS, `<base>.dll`
+ * on Windows (no `lib` prefix), `lib<base>.so` elsewhere. The platform
+ * string comes from the host (`process.platform` under Node/Bun, where
+ * Windows reports `win32`; `Deno.build.os`, where it reports `windows`);
+ * both spellings map to the Windows name here so the adapters cannot
+ * diverge.
+ *
+ * This file imports nothing, on purpose: strict-mode Deno consumers
+ * (notably `deno/build.ts`) import it directly, and any cross-file import
+ * with a `.js` suffix breaks Deno's strict resolution. Runtime code takes
+ * these through `artifact.ts`; nothing takes them the other way.
+ */
+export function artifactFileName(base, platform) {
+    if (platform === "darwin")
+        return `lib${base}.dylib`;
+    if (platform === "win32" || platform === "windows")
+        return `${base}.dll`;
+    return `lib${base}.so`;
+}
+/**
+ * Shared wasm artifact filename. WebAssembly modules are platform-neutral:
+ * always `lib<base>.wasm`.
+ */
+export function wasmArtifactFileName(base) {
+    return `lib${base}.wasm`;
+}
+//# sourceMappingURL=names.js.map

package/dist/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../src/names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAAgB;IAC7D,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,MAAM,IAAI,QAAQ,CAAC;IACrD,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,GAAG,IAAI,MAAM,CAAC;IACzE,OAAO,MAAM,IAAI,KAAK,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,MAAM,IAAI,OAAO,CAAC;AAC3B,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,45 @@
+import type { Session } from "./session.ts";
+/**
+ * Session-bound handle for a node in the non-relocating AST storage.
+ * Mirrors Python's `galley.Node`: keeps a strong reference to its Session
+ * and raises after the session is closed.
+ */
+export declare class Node {
+    #private;
+    constructor(session: Session, address: bigint | number);
+    /** Raw address (stable index in the session's node storage). */
+    get address(): bigint;
+    /** Owning session. */
+    get session(): Session;
+    private ensureAlive;
+    /** Tuple of direct children, from first to last (empty when leaf). */
+    children(): Node[];
+    /** Text bytes of this node, or null for invalid node. */
+    text(): Uint8Array | null;
+    /** Symbol name bytes as string, or null for invalid node. Terminal-only nodes → "". */
+    symbolName(): string | null;
+    /** Raw symbol name bytes (Uint8Array) or null. */
+    symbolNameBytes(): Uint8Array | null;
+    /** (start, length) byte span, or null. */
+    span(): [bigint, bigint] | null;
+    /** 1-based (line, column) of first byte, or null. */
+    lineColumn(): [number, number] | null;
+    /** Parent node, or null for root. */
+    parent(): Node | null;
+    nextSibling(): Node | null;
+    priorSibling(): Node | null;
+    firstChild(): Node | null;
+    lastChild(): Node | null;
+    cleanChildren(): Node | null;
+    appendChildren(chain: Node | bigint): void;
+    /** Number of direct children. */
+    get length(): number;
+    /** Child at index (negative indices supported). */
+    at(index: number): Node;
+    [Symbol.iterator](): Iterator<Node>;
+    /** Raw address for `Number(node)` / `BigInt(node)`. */
+    valueOf(): bigint;
+    toString(): string;
+    equals(other: unknown): boolean;
+    [Symbol.toPrimitive](hint: string): bigint | string | number;
+}

package/dist/node.js

@@ -0,0 +1,137 @@
+import { decodeUtf8 } from "./text.js";
+/**
+ * Session-bound handle for a node in the non-relocating AST storage.
+ * Mirrors Python's `galley.Node`: keeps a strong reference to its Session
+ * and raises after the session is closed.
+ */
+export class Node {
+    #session;
+    #address;
+    constructor(session, address) {
+        this.#session = session;
+        this.#address = typeof address === "bigint" ? address : BigInt(address);
+    }
+    /** Raw address (stable index in the session's node storage). */
+    get address() {
+        return this.#address;
+    }
+    /** Owning session. */
+    get session() {
+        return this.#session;
+    }
+    ensureAlive() {
+        if (this.#session.isClosed) {
+            throw new Error("node's session is closed");
+        }
+    }
+    /** Tuple of direct children, from first to last (empty when leaf). */
+    children() {
+        this.ensureAlive();
+        return this.#session.children(this);
+    }
+    /** Text bytes of this node, or null for invalid node. */
+    text() {
+        this.ensureAlive();
+        return this.#session.text(this);
+    }
+    /** Symbol name bytes as string, or null for invalid node. Terminal-only nodes → "". */
+    symbolName() {
+        this.ensureAlive();
+        const bytes = this.#session.symbolNameBytes(this);
+        if (bytes === null)
+            return null;
+        return decodeUtf8(bytes);
+    }
+    /** Raw symbol name bytes (Uint8Array) or null. */
+    symbolNameBytes() {
+        this.ensureAlive();
+        return this.#session.symbolNameBytes(this);
+    }
+    /** (start, length) byte span, or null. */
+    span() {
+        this.ensureAlive();
+        return this.#session.span(this);
+    }
+    /** 1-based (line, column) of first byte, or null. */
+    lineColumn() {
+        this.ensureAlive();
+        return this.#session.lineColumn(this);
+    }
+    /** Parent node, or null for root. */
+    parent() {
+        this.ensureAlive();
+        return this.#session.parent(this);
+    }
+    nextSibling() {
+        this.ensureAlive();
+        return this.#session.nextSibling(this);
+    }
+    priorSibling() {
+        this.ensureAlive();
+        return this.#session.priorSibling(this);
+    }
+    firstChild() {
+        this.ensureAlive();
+        return this.#session.firstChild(this);
+    }
+    lastChild() {
+        this.ensureAlive();
+        return this.#session.lastChild(this);
+    }
+    cleanChildren() {
+        this.ensureAlive();
+        return this.#session.cleanChildren(this);
+    }
+    appendChildren(chain) {
+        this.ensureAlive();
+        this.#session.appendChildren(this, chain);
+    }
+    /** Number of direct children. */
+    get length() {
+        this.ensureAlive();
+        return this.#session.childCount(this);
+    }
+    /** Child at index (negative indices supported). */
+    at(index) {
+        this.ensureAlive();
+        const count = this.length;
+        let i = index;
+        if (i < 0)
+            i += count;
+        if (i < 0 || i >= count)
+            throw new RangeError(`node index ${index} out of range (0..${count - 1})`);
+        const arr = this.children();
+        return arr[i];
+    }
+    *[Symbol.iterator]() {
+        this.ensureAlive();
+        for (const child of this.children())
+            yield child;
+    }
+    /** Raw address for `Number(node)` / `BigInt(node)`. */
+    valueOf() {
+        return this.#address;
+    }
+    toString() {
+        return `Node(${this.#address.toString()})`;
+    }
+    equals(other) {
+        if (other instanceof Node) {
+            return this.#address === other.#address && this.#session === other.#session;
+        }
+        if (typeof other === "bigint")
+            return this.#address === other;
+        if (typeof other === "number")
+            return this.#address === BigInt(other);
+        return false;
+    }
+    // allow `Number(node)` and `+node`
+    [Symbol.toPrimitive](hint) {
+        if (hint === "number")
+            return Number(this.#address);
+        if (hint === "string")
+            return this.toString();
+        return this.#address;
+    }
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}