@optique/core 1.0.0-dev.1611 → 1.0.0-dev.1658

package/dist/input-trace.cjs

@@ -0,0 +1,56 @@
+
+//#region src/input-trace.ts
+const symbolKeys = /* @__PURE__ */ new WeakMap();
+let symbolCounter = 0;
+/** Length-prefix a raw segment so that no delimiter escaping is needed. */
+function lengthPrefix(s) {
+	return `${s.length}:${s}`;
+}
+function serializeKey(key) {
+	if (typeof key === "string") return lengthPrefix(`s${key}`);
+	if (typeof key === "number") return lengthPrefix(`n${key}`);
+	const registeredKey = Symbol.keyFor(key);
+	if (registeredKey !== void 0) return lengthPrefix(`r${registeredKey}`);
+	let id = symbolKeys.get(key);
+	if (id === void 0) {
+		id = `y${symbolCounter++}`;
+		symbolKeys.set(key, id);
+	}
+	return lengthPrefix(id);
+}
+function serializePath(path) {
+	if (path.length === 0) return "";
+	return path.map(serializeKey).join("");
+}
+var InputTraceImpl = class InputTraceImpl {
+	#entries;
+	constructor(entries) {
+		this.#entries = entries ?? /* @__PURE__ */ new Map();
+	}
+	get(path) {
+		return this.#entries.get(serializePath(path));
+	}
+	set(path, entry) {
+		const copy = new Map(this.#entries);
+		copy.set(serializePath(path), entry);
+		return new InputTraceImpl(copy);
+	}
+	delete(path) {
+		const copy = new Map(this.#entries);
+		copy.delete(serializePath(path));
+		return new InputTraceImpl(copy);
+	}
+};
+/**
+* Creates a new empty {@link InputTrace}.
+*
+* @returns An empty immutable input trace.
+* @internal
+* @since 1.0.0
+*/
+function createInputTrace() {
+	return new InputTraceImpl();
+}
+
+//#endregion
+exports.createInputTrace = createInputTrace;

package/dist/input-trace.d.cts

@@ -0,0 +1,77 @@
+import { ValueParserResult } from "./valueparser.cjs";
+
+//#region src/input-trace.d.ts
+
+/**
+ * A replayable record of raw input consumed by a single parser node.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface TraceEntry {
+  /** The kind of input that was consumed. */
+  readonly kind: "option-value" | "argument-value" | "literal" | "custom";
+  /** The raw input string to be replayed. */
+  readonly rawInput: string;
+  /** The tokens consumed from the buffer. */
+  readonly consumed: readonly string[];
+  /** The preliminary parse result using default dependency values. */
+  readonly preliminaryResult?: ValueParserResult<unknown>;
+  /**
+   * Snapshotted default dependency values captured during parse.
+   *
+   * Present when a derived parser snapshots default dependency values during
+   * parse, including both `derive()` and `deriveFrom()` parsers.
+   * This avoids re-evaluating dynamic default thunks during replay.
+   */
+  readonly defaultDependencyValues?: readonly unknown[];
+  /** The option names that matched (e.g., `["--env", "-e"]`). */
+  readonly optionNames?: readonly string[];
+  /** The metavar of the value parser. */
+  readonly metavar?: string;
+}
+/**
+ * An immutable, path-keyed store of {@link TraceEntry} records.
+ *
+ * Each entry is keyed by a path of `PropertyKey` segments (strings, numbers,
+ * or symbols) corresponding to the position of the parser in the parse tree.
+ *
+ * All mutation methods return a new `InputTrace` instance; the original is
+ * never modified.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface InputTrace {
+  /**
+   * Retrieves the trace entry at the given path.
+   *
+   * @param path The path segments identifying the entry.
+   * @returns The entry, or `undefined` if no entry exists at that path.
+   */
+  get(path: readonly PropertyKey[]): TraceEntry | undefined;
+  /**
+   * Returns a new trace with the entry set at the given path.
+   *
+   * @param path The path segments identifying the entry.
+   * @param entry The trace entry to store.
+   * @returns A new `InputTrace` with the entry stored.
+   */
+  set(path: readonly PropertyKey[], entry: TraceEntry): InputTrace;
+  /**
+   * Returns a new trace with the entry at the given path removed.
+   *
+   * @param path The path segments identifying the entry to remove.
+   * @returns A new `InputTrace` without the entry.
+   */
+  delete(path: readonly PropertyKey[]): InputTrace;
+}
+/**
+ * Creates a new empty {@link InputTrace}.
+ *
+ * @returns An empty immutable input trace.
+ * @internal
+ * @since 1.0.0
+ */
+//#endregion
+export { InputTrace };

package/dist/input-trace.d.ts

@@ -0,0 +1,77 @@
+import { ValueParserResult } from "./valueparser.js";
+
+//#region src/input-trace.d.ts
+
+/**
+ * A replayable record of raw input consumed by a single parser node.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface TraceEntry {
+  /** The kind of input that was consumed. */
+  readonly kind: "option-value" | "argument-value" | "literal" | "custom";
+  /** The raw input string to be replayed. */
+  readonly rawInput: string;
+  /** The tokens consumed from the buffer. */
+  readonly consumed: readonly string[];
+  /** The preliminary parse result using default dependency values. */
+  readonly preliminaryResult?: ValueParserResult<unknown>;
+  /**
+   * Snapshotted default dependency values captured during parse.
+   *
+   * Present when a derived parser snapshots default dependency values during
+   * parse, including both `derive()` and `deriveFrom()` parsers.
+   * This avoids re-evaluating dynamic default thunks during replay.
+   */
+  readonly defaultDependencyValues?: readonly unknown[];
+  /** The option names that matched (e.g., `["--env", "-e"]`). */
+  readonly optionNames?: readonly string[];
+  /** The metavar of the value parser. */
+  readonly metavar?: string;
+}
+/**
+ * An immutable, path-keyed store of {@link TraceEntry} records.
+ *
+ * Each entry is keyed by a path of `PropertyKey` segments (strings, numbers,
+ * or symbols) corresponding to the position of the parser in the parse tree.
+ *
+ * All mutation methods return a new `InputTrace` instance; the original is
+ * never modified.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface InputTrace {
+  /**
+   * Retrieves the trace entry at the given path.
+   *
+   * @param path The path segments identifying the entry.
+   * @returns The entry, or `undefined` if no entry exists at that path.
+   */
+  get(path: readonly PropertyKey[]): TraceEntry | undefined;
+  /**
+   * Returns a new trace with the entry set at the given path.
+   *
+   * @param path The path segments identifying the entry.
+   * @param entry The trace entry to store.
+   * @returns A new `InputTrace` with the entry stored.
+   */
+  set(path: readonly PropertyKey[], entry: TraceEntry): InputTrace;
+  /**
+   * Returns a new trace with the entry at the given path removed.
+   *
+   * @param path The path segments identifying the entry to remove.
+   * @returns A new `InputTrace` without the entry.
+   */
+  delete(path: readonly PropertyKey[]): InputTrace;
+}
+/**
+ * Creates a new empty {@link InputTrace}.
+ *
+ * @returns An empty immutable input trace.
+ * @internal
+ * @since 1.0.0
+ */
+//#endregion
+export { InputTrace };

package/dist/input-trace.js

@@ -0,0 +1,55 @@
+//#region src/input-trace.ts
+const symbolKeys = /* @__PURE__ */ new WeakMap();
+let symbolCounter = 0;
+/** Length-prefix a raw segment so that no delimiter escaping is needed. */
+function lengthPrefix(s) {
+	return `${s.length}:${s}`;
+}
+function serializeKey(key) {
+	if (typeof key === "string") return lengthPrefix(`s${key}`);
+	if (typeof key === "number") return lengthPrefix(`n${key}`);
+	const registeredKey = Symbol.keyFor(key);
+	if (registeredKey !== void 0) return lengthPrefix(`r${registeredKey}`);
+	let id = symbolKeys.get(key);
+	if (id === void 0) {
+		id = `y${symbolCounter++}`;
+		symbolKeys.set(key, id);
+	}
+	return lengthPrefix(id);
+}
+function serializePath(path) {
+	if (path.length === 0) return "";
+	return path.map(serializeKey).join("");
+}
+var InputTraceImpl = class InputTraceImpl {
+	#entries;
+	constructor(entries) {
+		this.#entries = entries ?? /* @__PURE__ */ new Map();
+	}
+	get(path) {
+		return this.#entries.get(serializePath(path));
+	}
+	set(path, entry) {
+		const copy = new Map(this.#entries);
+		copy.set(serializePath(path), entry);
+		return new InputTraceImpl(copy);
+	}
+	delete(path) {
+		const copy = new Map(this.#entries);
+		copy.delete(serializePath(path));
+		return new InputTraceImpl(copy);
+	}
+};
+/**
+* Creates a new empty {@link InputTrace}.
+*
+* @returns An empty immutable input trace.
+* @internal
+* @since 1.0.0
+*/
+function createInputTrace() {
+	return new InputTraceImpl();
+}
+
+//#endregion
+export { createInputTrace };