@sectile/core 0.2.0 → 0.2.1

package/dist/structures/range.d.ts

@@ -0,0 +1,41 @@
+import { type Result, type TiePolicy } from '../shared.js';
+export interface RangeOptions {
+    readonly maxCount?: number;
+    readonly maxDecimalCodeUnits?: number;
+    readonly maxScale?: number;
+}
+export interface RangeInput extends RangeOptions {
+    readonly origin: string;
+    readonly step: string;
+    /** Highest tick. Cardinality is count + 1. */
+    readonly count: number;
+}
+export interface BoundedRangeInput extends RangeOptions {
+    readonly min: string;
+    readonly max: string;
+    readonly step: string;
+}
+export interface ExactRatio {
+    readonly numerator: bigint;
+    readonly denominator: bigint;
+}
+export interface QuantizedRange {
+    readonly origin: string;
+    readonly step: string;
+    readonly count: number;
+    readonly cardinality: number;
+    readonly lower: string;
+    readonly upper: string;
+    valueAt(tick: number): string | null;
+    tickOf(value: string): number | null;
+    clamp(value: string): string | null;
+    snap(value: string, tie?: TiePolicy): string | null;
+    ratioOfTick(tick: number): ExactRatio | null;
+    tickFromRatio(ratio: ExactRatio, tie?: TiePolicy): number | null;
+}
+export declare function createRange(input: RangeInput): QuantizedRange;
+export declare function tryCreateRange(input: RangeInput): Result<QuantizedRange>;
+export declare function createBoundedRange(input: BoundedRangeInput): QuantizedRange;
+export declare function tryCreateBoundedRange(input: BoundedRangeInput): Result<QuantizedRange>;
+export type { Result, TiePolicy } from '../shared.js';
+//# sourceMappingURL=range.d.ts.map

package/dist/structures/range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"range.d.ts","sourceRoot":"","sources":["../../src/structures/range.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAe3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACrC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACrC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;IACpD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAC7C,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;CAClE;AAkHD,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,CAE7D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,cAAc,CAAC,CAsDxE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,cAAc,CAE3E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC,cAAc,CAAC,CAkEtF;AAcD,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}

package/dist/structures/range.js

@@ -0,0 +1,249 @@
+import { unwrap } from '../result.js';
+import {} from '../shared.js';
+import { addDecimal, compareDecimal, decimalQuotient, decimalToString, floorFraction, multiplyDecimalByInteger, parseDecimal, reduceFraction, subtractDecimal, } from '../internal/kernel/decimal.js';
+import { fail, ok, validateSafeCeiling } from '../internal/kernel/foundation.js';
+class ExactQuantizedRange {
+    origin;
+    step;
+    count;
+    #origin;
+    #step;
+    constructor(origin, step, count) {
+        this.#origin = origin;
+        this.#step = step;
+        this.origin = decimalToString(origin);
+        this.step = decimalToString(step);
+        this.count = count;
+        Object.freeze(this);
+    }
+    get cardinality() {
+        return this.count + 1;
+    }
+    get lower() {
+        return this.origin;
+    }
+    get upper() {
+        return decimalToString(this.valueDecimal(this.count));
+    }
+    valueAt(tick) {
+        return validTick(tick, this.count) ? decimalToString(this.valueDecimal(tick)) : null;
+    }
+    tickOf(value) {
+        const parsed = parseDecimal(value);
+        if (parsed === null)
+            return null;
+        const [numerator, denominator] = decimalQuotient(subtractDecimal(parsed, this.#origin), this.#step);
+        if (denominator <= 0n || numerator % denominator !== 0n)
+            return null;
+        const tick = numerator / denominator;
+        return tick >= 0n && tick <= BigInt(this.count) ? Number(tick) : null;
+    }
+    clamp(value) {
+        const parsed = parseDecimal(value);
+        if (parsed === null)
+            return null;
+        if (compareDecimal(parsed, this.#origin) < 0)
+            return this.lower;
+        const upper = this.valueDecimal(this.count);
+        if (compareDecimal(parsed, upper) > 0)
+            return this.upper;
+        return decimalToString(parsed);
+    }
+    snap(value, tie = 'lower') {
+        const parsed = parseDecimal(value);
+        if (parsed === null || !isTiePolicy(tie))
+            return null;
+        const clamped = compareDecimal(parsed, this.#origin) < 0
+            ? this.#origin
+            : compareDecimal(parsed, this.valueDecimal(this.count)) > 0
+                ? this.valueDecimal(this.count)
+                : parsed;
+        const [numerator, denominator] = decimalQuotient(subtractDecimal(clamped, this.#origin), this.#step);
+        const floor = floorFraction(numerator, denominator);
+        const ceil = numerator % denominator === 0n ? floor : floor + 1n;
+        const boundedFloor = clampBigInt(floor, 0n, BigInt(this.count));
+        const boundedCeil = clampBigInt(ceil, 0n, BigInt(this.count));
+        const lowerDistance = numerator - boundedFloor * denominator;
+        const upperDistance = boundedCeil * denominator - numerator;
+        let tick;
+        if (lowerDistance < upperDistance)
+            tick = boundedFloor;
+        else if (upperDistance < lowerDistance)
+            tick = boundedCeil;
+        else if (tie === 'lower')
+            tick = boundedFloor;
+        else if (tie === 'upper')
+            tick = boundedCeil;
+        else
+            tick = boundedFloor % 2n === 0n ? boundedFloor : boundedCeil;
+        return decimalToString(this.valueDecimal(Number(tick)));
+    }
+    ratioOfTick(tick) {
+        if (!validTick(tick, this.count))
+            return null;
+        if (this.count === 0)
+            return Object.freeze({ numerator: 0n, denominator: 1n });
+        const [numerator, denominator] = reduceFraction(BigInt(tick), BigInt(this.count));
+        return Object.freeze({ numerator, denominator });
+    }
+    tickFromRatio(ratio, tie = 'lower') {
+        if (ratio.denominator === 0n || !isTiePolicy(tie))
+            return null;
+        let numerator = ratio.numerator;
+        let denominator = ratio.denominator;
+        if (denominator < 0n) {
+            numerator = -numerator;
+            denominator = -denominator;
+        }
+        numerator = clampBigInt(numerator, 0n, denominator);
+        if (this.count === 0)
+            return 0;
+        const scaled = numerator * BigInt(this.count);
+        const floor = scaled / denominator;
+        const ceil = scaled % denominator === 0n ? floor : floor + 1n;
+        const lowerDistance = scaled - floor * denominator;
+        const upperDistance = ceil * denominator - scaled;
+        if (lowerDistance < upperDistance)
+            return Number(floor);
+        if (upperDistance < lowerDistance)
+            return Number(ceil);
+        if (tie === 'lower')
+            return Number(floor);
+        if (tie === 'upper')
+            return Number(ceil);
+        return Number(floor % 2n === 0n ? floor : ceil);
+    }
+    valueDecimal(tick) {
+        return addDecimal(this.#origin, multiplyDecimalByInteger(this.#step, BigInt(tick)));
+    }
+}
+export function createRange(input) {
+    return unwrap(tryCreateRange(input));
+}
+export function tryCreateRange(input) {
+    const maxCount = input.maxCount ?? 10_000_000;
+    const maxDecimalCodeUnits = input.maxDecimalCodeUnits ?? 1_024;
+    const maxScale = input.maxScale ?? 100;
+    for (const [value, name, minimum] of [
+        [maxCount, 'maxCount', 0],
+        [maxDecimalCodeUnits, 'maxDecimalCodeUnits', 1],
+        [maxScale, 'maxScale', 0],
+    ]) {
+        const error = validateSafeCeiling(value, name, minimum);
+        if (error !== null)
+            return { ok: false, error };
+    }
+    const countError = validateSafeCeiling(input.count, 'count');
+    if (countError !== null)
+        return { ok: false, error: countError };
+    if (input.count >= Number.MAX_SAFE_INTEGER) {
+        return fail('resource-rejection', 'cardinality-not-safe', 'count + 1 must remain within the safe integer domain.', { count: input.count });
+    }
+    if (input.count > maxCount) {
+        return fail('resource-rejection', 'count-ceiling-exceeded', 'Range count exceeds maxCount.', {
+            count: input.count,
+            maxCount,
+        });
+    }
+    for (const [value, name] of [
+        [input.origin, 'origin'],
+        [input.step, 'step'],
+    ]) {
+        if (value.length > maxDecimalCodeUnits) {
+            return fail('resource-rejection', 'decimal-code-unit-ceiling-exceeded', `${name} exceeds maxDecimalCodeUnits.`, {
+                name,
+                codeUnits: value.length,
+                maxDecimalCodeUnits,
+            });
+        }
+    }
+    const origin = parseDecimal(input.origin);
+    const step = parseDecimal(input.step);
+    if (origin === null || step === null) {
+        return fail('construction', 'invalid-decimal', 'origin and step must be finite canonical decimal spellings.');
+    }
+    if (origin.scale > maxScale || step.scale > maxScale) {
+        return fail('resource-rejection', 'decimal-scale-ceiling-exceeded', 'Decimal scale exceeds maxScale.', {
+            maxScale,
+        });
+    }
+    if (step.coefficient <= 0n) {
+        return fail('construction', 'non-positive-step', 'step must be greater than zero.');
+    }
+    return ok(new ExactQuantizedRange(origin, step, input.count));
+}
+export function createBoundedRange(input) {
+    return unwrap(tryCreateBoundedRange(input));
+}
+export function tryCreateBoundedRange(input) {
+    const maxCount = input.maxCount ?? 10_000_000;
+    const maxDecimalCodeUnits = input.maxDecimalCodeUnits ?? 1_024;
+    const maxScale = input.maxScale ?? 100;
+    for (const [value, name, minimum] of [
+        [maxCount, 'maxCount', 0],
+        [maxDecimalCodeUnits, 'maxDecimalCodeUnits', 1],
+        [maxScale, 'maxScale', 0],
+    ]) {
+        const error = validateSafeCeiling(value, name, minimum);
+        if (error !== null)
+            return { ok: false, error };
+    }
+    for (const [value, name] of [
+        [input.min, 'min'],
+        [input.max, 'max'],
+        [input.step, 'step'],
+    ]) {
+        if (value.length > maxDecimalCodeUnits) {
+            return fail('resource-rejection', 'decimal-code-unit-ceiling-exceeded', `${name} exceeds maxDecimalCodeUnits.`, { name, codeUnits: value.length, maxDecimalCodeUnits });
+        }
+    }
+    const min = parseDecimal(input.min);
+    const max = parseDecimal(input.max);
+    const step = parseDecimal(input.step);
+    if (min === null || max === null || step === null) {
+        return fail('construction', 'invalid-decimal', 'min, max, and step must be finite decimal spellings.');
+    }
+    if (min.scale > maxScale || max.scale > maxScale || step.scale > maxScale) {
+        return fail('resource-rejection', 'decimal-scale-ceiling-exceeded', 'Decimal scale exceeds maxScale.', {
+            maxScale,
+        });
+    }
+    if (compareDecimal(max, min) < 0) {
+        return fail('construction', 'inverted-bounds', 'max must be greater than or equal to min.');
+    }
+    if (step.coefficient <= 0n) {
+        return fail('construction', 'non-positive-step', 'step must be greater than zero.');
+    }
+    const [numerator, denominator] = decimalQuotient(subtractDecimal(max, min), step);
+    if (numerator < 0n || numerator % denominator !== 0n) {
+        return fail('construction', 'endpoint-off-lattice', 'The upper endpoint must be on the range lattice.');
+    }
+    const count = numerator / denominator;
+    if (count >= BigInt(Number.MAX_SAFE_INTEGER)) {
+        return fail('resource-rejection', 'count-not-safe', 'Derived count exceeds the safe integer domain.');
+    }
+    if (count > BigInt(maxCount)) {
+        return fail('resource-rejection', 'count-ceiling-exceeded', 'Derived range count exceeds maxCount.', {
+            count: count.toString(),
+            maxCount,
+        });
+    }
+    return tryCreateRange({
+        origin: input.min,
+        step: input.step,
+        count: Number(count),
+        maxCount,
+        maxDecimalCodeUnits,
+        maxScale,
+    });
+}
+function validTick(tick, count) {
+    return Number.isSafeInteger(tick) && tick >= 0 && tick <= count;
+}
+function isTiePolicy(value) {
+    return value === 'lower' || value === 'upper' || value === 'even-tick';
+}
+function clampBigInt(value, lower, upper) {
+    return value < lower ? lower : value > upper ? upper : value;
+}
+//# sourceMappingURL=range.js.map

package/dist/structures/range.js.map

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

package/dist/structures/sequence.d.ts

@@ -0,0 +1,19 @@
+import { type BoundaryPolicy, type Direction, type MoveResult, type ResourceCeilings, type Result, type ScanOptions, type StableID } from '../shared.js';
+export interface SequenceOptions extends ResourceCeilings {
+    readonly maxItems?: number;
+}
+export type SequenceProjectionPredicate<ID extends StableID = StableID> = (id: ID, index: number) => boolean;
+export interface Sequence<ID extends StableID = StableID> {
+    readonly size: number;
+    readonly ids: readonly ID[];
+    at(index: number): ID | null;
+    indexOf(id: ID): number | null;
+    contains(id: ID): boolean;
+    compare(left: ID, right: ID): -1 | 0 | 1 | null;
+    project(predicate: SequenceProjectionPredicate<ID>): Sequence<ID>;
+    move(current: ID, direction: Direction, boundary?: BoundaryPolicy, options?: ScanOptions<ID>): MoveResult<ID>;
+}
+export declare function createSequence<ID extends StableID>(ids: readonly ID[], options?: SequenceOptions): Sequence<ID>;
+export declare function tryCreateSequence<ID extends StableID>(ids: readonly ID[], options?: SequenceOptions): Result<Sequence<ID>>;
+export type { BoundaryPolicy, Direction, MoveResult, Result, ScanOptions, SectileError, StableID, } from '../shared.js';
+//# sourceMappingURL=sequence.d.ts.map

package/dist/structures/sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../src/structures/sequence.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,KAAK,QAAQ,EACd,MAAM,cAAc,CAAC;AAItB,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,2BAA2B,CAAC,EAAE,SAAS,QAAQ,GAAG,QAAQ,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE7G,MAAM,WAAW,QAAQ,CAAC,EAAE,SAAS,QAAQ,GAAG,QAAQ;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC;IAC5B,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;IAC1B,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAChD,OAAO,CAAC,SAAS,EAAE,2BAA2B,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IAClE,IAAI,CACF,OAAO,EAAE,EAAE,EACX,SAAS,EAAE,SAAS,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,OAAO,CAAC,EAAE,WAAW,CAAC,EAAE,CAAC,GACxB,UAAU,CAAC,EAAE,CAAC,CAAC;CACnB;AAED,wBAAgB,cAAc,CAAC,EAAE,SAAS,QAAQ,EAChD,GAAG,EAAE,SAAS,EAAE,EAAE,EAClB,OAAO,GAAE,eAAoB,GAC5B,QAAQ,CAAC,EAAE,CAAC,CAEd;AAED,wBAAgB,iBAAiB,CAAC,EAAE,SAAS,QAAQ,EACnD,GAAG,EAAE,SAAS,EAAE,EAAE,EAClB,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAgBtB;AAED,YAAY,EACV,cAAc,EACd,SAAS,EACT,UAAU,EACV,MAAM,EACN,WAAW,EACX,YAAY,EACZ,QAAQ,GACT,MAAM,cAAc,CAAC"}

package/dist/structures/sequence.js

@@ -0,0 +1,28 @@
+import { unwrap } from '../result.js';
+import { DEFAULT_MAX_ID_CODE_UNITS, } from '../shared.js';
+import { fail, ok, validateSafeCeiling, validateUniqueIDs } from '../internal/kernel/foundation.js';
+import { IndexedSequence } from '../internal/kernel/indexed-sequence.js';
+export function createSequence(ids, options = {}) {
+    return unwrap(tryCreateSequence(ids, options));
+}
+export function tryCreateSequence(ids, options = {}) {
+    const maxItems = options.maxItems ?? 100_000;
+    const ceilingError = validateSafeCeiling(maxItems, 'maxItems');
+    if (ceilingError !== null)
+        return { ok: false, error: ceilingError };
+    const maxIDCodeUnits = options.maxIDCodeUnits ?? DEFAULT_MAX_ID_CODE_UNITS;
+    const idCeilingError = validateSafeCeiling(maxIDCodeUnits, 'maxIDCodeUnits', 1);
+    if (idCeilingError !== null)
+        return { ok: false, error: idCeilingError };
+    if (ids.length > maxItems) {
+        return fail('resource-rejection', 'item-ceiling-exceeded', 'Sequence exceeds maxItems.', {
+            size: ids.length,
+            maxItems,
+        });
+    }
+    const validated = validateUniqueIDs(ids, maxIDCodeUnits);
+    if (!validated.ok)
+        return validated;
+    return ok(new IndexedSequence(validated.value));
+}
+//# sourceMappingURL=sequence.js.map

package/dist/structures/sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.js","sourceRoot":"","sources":["../../src/structures/sequence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EACL,yBAAyB,GAQ1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACpG,OAAO,EAAE,eAAe,EAAqB,MAAM,wCAAwC,CAAC;AAwB5F,MAAM,UAAU,cAAc,CAC5B,GAAkB,EAClB,OAAO,GAAoB,EAAE;IAE7B,OAAO,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,GAAkB,EAClB,OAAO,GAAoB,EAAE;IAE7B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC;IAC7C,MAAM,YAAY,GAAG,mBAAmB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC/D,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IACrE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,yBAAyB,CAAC;IAC3E,MAAM,cAAc,GAAG,mBAAmB,CAAC,cAAc,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;IAChF,IAAI,cAAc,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;IACzE,IAAI,GAAG,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,oBAAoB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE;YACvF,IAAI,EAAE,GAAG,CAAC,MAAM;YAChB,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;IACD,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACzD,IAAI,CAAC,SAAS,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IACpC,OAAO,EAAE,CAAC,IAAI,eAAe,CAAC,SAAS,CAAC,KAAK,CAAqB,CAAC,CAAC;AACtE,CAAC"}

package/dist/structures/tree.d.ts

@@ -0,0 +1,33 @@
+import { type ResourceCeilings, type Result, type StableID } from '../shared.js';
+import type { Sequence } from './sequence.js';
+export interface TreeNodeInput<ID extends StableID = StableID> {
+    readonly id: ID;
+    readonly parentID: ID | null;
+}
+export interface TreeOptions extends ResourceCeilings {
+    readonly maxItems?: number;
+    readonly maxDepth?: number;
+}
+export interface Tree<ID extends StableID = StableID> {
+    readonly size: number;
+    readonly roots: Sequence<ID>;
+    has(id: ID): boolean;
+    parentOf(id: ID): ID | null;
+    childrenOf(id: ID): Sequence<ID> | null;
+    isLeaf(id: ID): boolean | null;
+    depthOf(id: ID): number | null;
+    ancestorsOf(id: ID): readonly ID[] | null;
+    preorder(): Sequence<ID>;
+    postorder(): Sequence<ID>;
+    normalizeExpansion(expanded: Iterable<ID>): Expansion<ID>;
+    visible(expansion: Expansion<ID> | Iterable<ID>): Sequence<ID>;
+}
+export interface Expansion<ID extends StableID = StableID> {
+    readonly ids: readonly ID[];
+    readonly size: number;
+    has(id: ID): boolean;
+}
+export declare function createTree<ID extends StableID>(nodes: readonly TreeNodeInput<ID>[], options?: TreeOptions): Tree<ID>;
+export declare function tryCreateTree<ID extends StableID>(nodes: readonly TreeNodeInput<ID>[], options?: TreeOptions): Result<Tree<ID>>;
+export type { Result, StableID } from '../shared.js';
+//# sourceMappingURL=tree.d.ts.map

package/dist/structures/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/structures/tree.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACX,KAAK,QAAQ,EACd,MAAM,cAAc,CAAC;AAStB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,aAAa,CAAC,EAAE,SAAS,QAAQ,GAAG,QAAQ;IAC3D,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,QAAQ,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,IAAI,CAAC,EAAE,SAAS,QAAQ,GAAG,QAAQ;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,EAAE,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACxC,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,EAAE,EAAE,GAAG,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC;IAC1C,QAAQ,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAC;IACzB,SAAS,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1B,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;IAC1D,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,SAAS,CAAC,EAAE,SAAS,QAAQ,GAAG,QAAQ;IACvD,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;CACtB;AA6HD,wBAAgB,UAAU,CAAC,EAAE,SAAS,QAAQ,EAC5C,KAAK,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,EAAE,EACnC,OAAO,GAAE,WAAgB,GACxB,IAAI,CAAC,EAAE,CAAC,CAEV;AAED,wBAAgB,aAAa,CAAC,EAAE,SAAS,QAAQ,EAC/C,KAAK,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,EAAE,EACnC,OAAO,GAAE,WAAgB,GACxB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAgIlB;AAWD,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC"}

package/dist/structures/tree.js

@@ -0,0 +1,238 @@
+import { unwrap } from '../result.js';
+import { DEFAULT_MAX_ID_CODE_UNITS, } from '../shared.js';
+import { fail, freezeArray, ok, validateSafeCeiling, validateStableID, } from '../internal/kernel/foundation.js';
+import { IndexedSequence } from '../internal/kernel/indexed-sequence.js';
+class NormalizedExpansion {
+    ids;
+    #set;
+    constructor(ids) {
+        this.ids = freezeArray(ids);
+        this.#set = new Set(ids);
+        Object.freeze(this);
+    }
+    get size() {
+        return this.ids.length;
+    }
+    has(id) {
+        return this.#set.has(id);
+    }
+}
+class IndexedTree {
+    size;
+    roots;
+    #parent;
+    #children;
+    #depth;
+    #preorder;
+    #postorder;
+    constructor(roots, parent, children, depth, preorder, postorder) {
+        this.size = preorder.length;
+        this.roots = new IndexedSequence(roots);
+        this.#parent = parent;
+        this.#children = children;
+        this.#depth = depth;
+        this.#preorder = freezeArray(preorder);
+        this.#postorder = freezeArray(postorder);
+        Object.freeze(this);
+    }
+    has(id) {
+        return this.#parent.has(id);
+    }
+    parentOf(id) {
+        return this.#parent.get(id) ?? null;
+    }
+    childrenOf(id) {
+        const children = this.#children.get(id);
+        return children === undefined ? null : new IndexedSequence(children);
+    }
+    isLeaf(id) {
+        const children = this.#children.get(id);
+        return children === undefined ? null : children.length === 0;
+    }
+    depthOf(id) {
+        return this.#depth.get(id) ?? null;
+    }
+    ancestorsOf(id) {
+        if (!this.#parent.has(id))
+            return null;
+        const result = [];
+        let current = this.#parent.get(id) ?? null;
+        while (current !== null) {
+            result.push(current);
+            current = this.#parent.get(current) ?? null;
+        }
+        return freezeArray(result);
+    }
+    preorder() {
+        return new IndexedSequence(this.#preorder);
+    }
+    postorder() {
+        return new IndexedSequence(this.#postorder);
+    }
+    normalizeExpansion(expanded) {
+        const requested = new Set(expanded);
+        const normalized = this.#preorder.filter((id) => requested.has(id) && (this.#children.get(id)?.length ?? 0) > 0);
+        return new NormalizedExpansion(normalized);
+    }
+    visible(expansion) {
+        const normalized = expansion instanceof NormalizedExpansion
+            ? expansion
+            : this.normalizeExpansion(isExpansion(expansion) ? expansion.ids : expansion);
+        const result = [];
+        const stack = [...this.roots.ids].reverse();
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (id === undefined)
+                continue;
+            result.push(id);
+            if (!normalized.has(id))
+                continue;
+            const children = this.#children.get(id) ?? [];
+            for (let index = children.length - 1; index >= 0; index -= 1) {
+                const child = children[index];
+                if (child !== undefined)
+                    stack.push(child);
+            }
+        }
+        return new IndexedSequence(result);
+    }
+}
+export function createTree(nodes, options = {}) {
+    return unwrap(tryCreateTree(nodes, options));
+}
+export function tryCreateTree(nodes, options = {}) {
+    const maxItems = options.maxItems ?? 100_000;
+    const maxDepth = options.maxDepth ?? 1_024;
+    const maxIDCodeUnits = options.maxIDCodeUnits ?? DEFAULT_MAX_ID_CODE_UNITS;
+    for (const [value, name] of [
+        [maxItems, 'maxItems'],
+        [maxDepth, 'maxDepth'],
+        [maxIDCodeUnits, 'maxIDCodeUnits'],
+    ]) {
+        const error = validateSafeCeiling(value, name);
+        if (error !== null)
+            return { ok: false, error };
+    }
+    if (maxIDCodeUnits < 1) {
+        return fail('construction', 'invalid-max-id-code-units', 'maxIDCodeUnits must be a positive safe integer.', { maxIDCodeUnits });
+    }
+    if (nodes.length > maxItems) {
+        return fail('resource-rejection', 'item-ceiling-exceeded', 'Tree exceeds maxItems.', {
+            size: nodes.length,
+            maxItems,
+        });
+    }
+    const parent = new Map();
+    const ids = [];
+    for (let index = 0; index < nodes.length; index += 1) {
+        const node = nodes[index];
+        if (node === undefined) {
+            return fail('construction', 'invalid-node', 'Tree input must not contain sparse or missing nodes.', { index });
+        }
+        const idError = validateStableID(node.id, maxIDCodeUnits);
+        if (idError !== null)
+            return { ok: false, error: idError };
+        if (parent.has(node.id)) {
+            return fail('construction', 'duplicate-id', 'Tree identities must be unique.', {
+                id: node.id,
+                index,
+            });
+        }
+        if (node.parentID === node.id) {
+            return fail('construction', 'self-parent', 'A tree node cannot be its own parent.', {
+                id: node.id,
+            });
+        }
+        parent.set(node.id, node.parentID);
+        ids.push(node.id);
+    }
+    for (const id of ids) {
+        const parentID = parent.get(id) ?? null;
+        if (parentID !== null && !parent.has(parentID)) {
+            return fail('construction', 'missing-parent', 'Every non-root parent must exist.', {
+                id,
+                parentID,
+            });
+        }
+    }
+    const childrenMutable = new Map();
+    for (const id of ids)
+        childrenMutable.set(id, []);
+    const roots = [];
+    for (const id of ids) {
+        const parentID = parent.get(id) ?? null;
+        if (parentID === null)
+            roots.push(id);
+        else
+            childrenMutable.get(parentID)?.push(id);
+    }
+    const marks = new Map();
+    const depth = new Map();
+    const preorder = [];
+    const postorder = [];
+    for (const root of roots) {
+        const stack = [{ id: root, depth: 0, nextChild: 0 }];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            if (frame === undefined)
+                break;
+            if (frame.nextChild === 0) {
+                const mark = marks.get(frame.id) ?? 0;
+                if (mark === 1) {
+                    return fail('construction', 'cycle', 'Tree parent relation must be acyclic.', {
+                        id: frame.id,
+                    });
+                }
+                if (mark === 2) {
+                    stack.pop();
+                    continue;
+                }
+                if (frame.depth > maxDepth) {
+                    return fail('resource-rejection', 'depth-ceiling-exceeded', 'Tree exceeds maxDepth.', {
+                        id: frame.id,
+                        depth: frame.depth,
+                        maxDepth,
+                    });
+                }
+                marks.set(frame.id, 1);
+                depth.set(frame.id, frame.depth);
+                preorder.push(frame.id);
+            }
+            const children = childrenMutable.get(frame.id) ?? [];
+            const child = children[frame.nextChild];
+            if (child !== undefined) {
+                frame.nextChild += 1;
+                const childMark = marks.get(child) ?? 0;
+                if (childMark === 1) {
+                    return fail('construction', 'cycle', 'Tree parent relation must be acyclic.', {
+                        id: child,
+                    });
+                }
+                if (childMark === 0) {
+                    stack.push({ id: child, depth: frame.depth + 1, nextChild: 0 });
+                }
+                continue;
+            }
+            marks.set(frame.id, 2);
+            postorder.push(frame.id);
+            stack.pop();
+        }
+    }
+    if (preorder.length !== ids.length) {
+        const unvisited = ids.find((id) => (marks.get(id) ?? 0) !== 2);
+        return fail('construction', 'cycle', 'Every tree node must be reachable from a root.', {
+            ...(unvisited === undefined ? {} : { id: unvisited }),
+        });
+    }
+    const children = new Map();
+    for (const [id, values] of childrenMutable)
+        children.set(id, freezeArray(values));
+    return ok(new IndexedTree(roots, parent, children, depth, preorder, postorder));
+}
+function isExpansion(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'ids' in value &&
+        Array.isArray(value.ids));
+}
+//# sourceMappingURL=tree.js.map