A platform for community discussion. Free, open, simple.
DEV: Replace dag-map with a locality-preserving topological sort (#39204)
Sérgio Saquetim885ec528692c
diff --git a/frontend/discourse/app/lib/dag.js b/frontend/discourse/app/lib/dag.jsdeleted file mode 100644index d7d8e653238..00000000000--- a/frontend/discourse/app/lib/dag.js+++ /dev/null@@ -1,294 +0,0 @@-import DAGMap from "dag-map";-import { bind } from "discourse/lib/decorators";-import { makeArray } from "discourse/lib/helpers";--export default class DAG {- /**- * Creates a new DAG instance from an iterable of entries.- *- * @param {Iterable<[string, any, Object?]>} entriesLike - An iterable of key-value-position tuples to initialize the DAG.- * @param {Object} [opts] - Optional configuration object.- * @param {Object} [opts.defaultPosition] - Default positioning rules for new items.- * @param {boolean} [opts.throwErrorOnCycle=true] - Flag indicating whether to throw an error when a cycle is detected. Default is true. When false, the default position will be used instead.- * @param {string|string[]} [opts.defaultPosition.before] - A key or array of keys of items which should appear before this one.- * @param {string|string[]} [opts.defaultPosition.after] - A key or array of keys of items which should appear after this one.- * @param {(key: string, value: any, position: {before?: string|string[], after?: string|string[]}) => void} [opts.onAddItem] - Callback function to be called when an item is added.- * @param {(key: string) => void} [opts.onDeleteItem] - Callback function to be called when an item is removed.- * @param {(key: string, newValue: any, oldValue: any, newPosition: {before?: string|string[], after?: string|string[]}, oldPosition: {before?: string|string[], after?: string|string[]}) => void} [opts.onReplaceItem] - Callback function to be called when an item is replaced.- * @param {(key: string, newPosition: {before?: string|string[], after?: string|string[]}, oldPosition: {before?: string|string[], after?: string|string[]}) => void} [opts.onRepositionItem] - Callback function to be called when an item is repositioned.- * @returns {DAG} A new DAG instance.- */- static from(entriesLike, opts) {- const dag = new this(opts);-- for (const [key, value, position] of entriesLike) {- dag.add(key, value, position);- }-- return dag;- }-- #defaultPosition;- #onAddItem;- #onDeleteItem;- #onReplaceItem;- #onRepositionItem;- #throwErrorOnCycle;-- #rawData = new Map();- #dag = new DAGMap();-- /**- * Creates a new Directed Acyclic Graph (DAG) instance.- *- * @param {Object} [opts] - Optional configuration object.- * @param {Object} [opts.defaultPosition] - Default positioning rules for new items.- * @param {boolean} [opts.throwErrorOnCycle=true] - Flag indicating whether to throw an error when a cycle is detected. When false, the default position will be used instead.- * @param {string|string[]} [opts.defaultPosition.before] - A key or array of keys of items which should appear before this one.- * @param {string|string[]} [opts.defaultPosition.after] - A key or array of keys of items which should appear after this one.- * @param {(key: string, value: any, position: {before?: string|string[], after?: string|string[]}) => void} [opts.onAddItem] - Callback function to be called when an item is added.- * @param {(key: string) => void} [opts.onDeleteItem] - Callback function to be called when an item is removed.- * @param {(key: string, newValue: any, oldValue: any, newPosition: {before?: string|string[], after?: string|string[]}, oldPosition: {before?: string|string[], after?: string|string[]}) => void} [opts.onReplaceItem] - Callback function to be called when an item is replaced.- * @param {(key: string, newPosition: {before?: string|string[], after?: string|string[]}, oldPosition: {before?: string|string[], after?: string|string[]}) => void} [opts.onRepositionItem] - Callback function to be called when an item is repositioned.- */- constructor(opts) {- // allows for custom default positioning of new items added to the DAG, eg- // new DAG({ defaultPosition: { before: "foo", after: "bar" } });- this.#defaultPosition = opts?.defaultPosition || {};- this.#throwErrorOnCycle = opts?.throwErrorOnCycle ?? true;-- this.#onAddItem = opts?.onAddItem;- this.#onDeleteItem = opts?.onDeleteItem;- this.#onReplaceItem = opts?.onReplaceItem;- this.#onRepositionItem = opts?.onRepositionItem;- }-- /**- * Returns the default position for a given key, excluding the key itself from the before/after arrays.- *- * @param {string} key - The key to get the default position for.- * @returns {Object} The default position object.- * @private- */- #defaultPositionForKey(key) {- const pos = { ...this.#defaultPosition };- if (makeArray(pos.before).includes(key)) {- delete pos.before;- }- if (makeArray(pos.after).includes(key)) {- delete pos.after;- }- return pos;- }-- /**- * Adds a key/value pair to the DAG map. Can optionally specify before/after position requirements.- *- * @param {string} key - The key of the item to be added. Can be referenced by other member's position parameters.- * @param {any} value - The value of the item to be added.- * @param {Object} [position] - The position object specifying before/after requirements.- * @param {string|string[]} [position.before] - A key or array of keys of items which should appear before this one.- * @param {string|string[]} [position.after] - A key or array of keys of items which should appear after this one.- * @returns {boolean} True if the item was added, false if the key already exists.- */- add(key, value, position) {- if (this.has(key)) {- return false;- }-- position ||= this.#defaultPositionForKey(key);- const { before, after } = position;- this.#rawData.set(key, {- value,- before,- after,- });-- this.#addHandlingCycles(this.#dag, key, value, before, after);- this.#onAddItem?.(key, value, position);-- return true;- }-- /**- * Remove an item from the map by key.- *- * @param {string} key - The key of the item to be removed.- * @returns {boolean} True if the item was deleted, false otherwise.- */- delete(key) {- const deleted = this.#rawData.delete(key);- this.#refreshDAG();-- if (deleted) {- this.#onDeleteItem?.(key);- }-- return deleted;- }-- /**- * Replace an existing item in the map.- *- * @param {string} key - The key of the item to be replaced.- * @param {any} value - The new value of the item.- * @param {Object} position - The new position object specifying before/after requirements.- * @param {string|string[]} [position.before] - A key or array of keys of items which should appear before this one.- * @param {string|string[]} [position.after] - A key or array of keys of items which should appear after this one.- * @returns {boolean} True if the item was replaced, false otherwise.- */- replace(key, value, position) {- return this.#replace(key, value, position);- }-- /**- * Change the positioning rules of an existing item in the map. Will replace all existing rules.- *- * @param {string} key - The key of the item to reposition.- * @param {Object} position - The new position object specifying before/after requirements.- * @param {string|string[]} [position.before] - A key or array of keys of items which should appear before this one.- * @param {string|string[]} [position.after] - A key or array of keys of items which should appear after this one.- * @returns {boolean} True if the item was repositioned, false otherwise.- */- reposition(key, position) {- if (!this.has(key) || !position) {- return false;- }-- const { value } = this.#rawData.get(key);-- return this.#replace(key, value, position, { repositionOnly: true });- }-- /**- * Check whether an item exists in the map.- *- * @param {string} key - The key to check for existence.- * @returns {boolean} True if the item exists, false otherwise.- */- has(key) {- return this.#rawData.has(key);- }-- /**- * Returns an array of entries in the DAG. Each entry is a tuple containing the key, value, and position object.- *- * @returns {Array<[string, any, {before?: string|string[], after?: string|string[]}]>} An array of key-value-position tuples.- */- entries() {- return Array.from(this.#rawData.entries()).map(- ([key, { value, before, after }]) => [key, value, { before, after }]- );- }-- /**- * Return the resolved key/value pairs in the map. The order of the pairs is determined by the before/after rules.- *- * @returns {Array<{key: string, value: any, position: {before?: string|string[], after?: string|string[]}}>} An array of key/value/position objects.- */- @bind- resolve() {- const result = [];- this.#dag.each((key, value) => {- // We need to filter keys that do not exist in the rawData because the DAGMap will insert a vertex for- // dependencies, for example if an item has a "before: search" dependency, the "search" vertex will be included- // even if it was explicitly excluded from the raw data.- if (this.has(key)) {- const { before, after } = this.#rawData.get(key);- result.push({ key, value, position: { before, after } });- }- });- return result;- }-- /**- * Adds a key/value pair to the DAG map while handling potential cycles.- *- * @param {DAGMap} dag - The DAG map instance to add the key/value pair to.- * @param {string} key - The key of the item to be added.- * @param {any} value - The value of the item to be added.- * @param {string|string[]} [before] - A key or array of keys of items which should appear before this one.- * @param {string|string[]} [after] - A key or array of keys of items which should appear after this one.- * @throws {Error} Throws an error if a cycle is detected and `throwErrorOnCycle` is true.- * @private- */- #addHandlingCycles(dag, key, value, before, after) {- if (this.#throwErrorOnCycle) {- dag.add(key, value, before, after);- } else {- try {- dag.add(key, value, before, after);- } catch (e) {- if (e.message.match(/cycle/i)) {- const { before: newBefore, after: newAfter } =- this.#defaultPositionForKey(key);-- // if even the default position causes a cycle, an error will be thrown- dag.add(key, value, newBefore, newAfter);- }- }- }- }-- /**- * Replace an existing item in the map.- *- * @param {string} key - The key of the item to be replaced.- * @param {any} value - The new value of the item.- * @param {Object} position - The new position object specifying before/after requirements.- * @param {string|string[]} [position.before] - A key or array of keys of items which should appear before this one.- * @param {string|string[]} [position.after] - A key or array of keys of items which should appear after this one.- * @param {Object} [options] - Additional options.- * @param {boolean} [options.repositionOnly=false] - Whether the replacement is for repositioning only.- * @returns {boolean} True if the item was replaced, false otherwise.- * @private- */- #replace(- key,- value,- position,- { repositionOnly } = { repositionOnly: false }- ) {- if (!this.has(key)) {- return false;- }-- const existingItem = this.#rawData.get(key);- const oldValue = existingItem.value;- const oldPosition = {- before: existingItem.before,- after: existingItem.after,- };-- // mutating the existing item keeps the position in the map in case before/after weren't explicitly set- existingItem.value = value;-- if (position) {- existingItem.before = position.before;- existingItem.after = position.after;- }-- this.#refreshDAG();-- if (repositionOnly) {- this.#onRepositionItem?.(key, position, oldPosition);- } else {- this.#onReplaceItem?.(key, value, oldValue, position, oldPosition);- }-- return true;- }-- /**- * Refreshes the DAG by recreating it from the raw data.- *- * @private- */- #refreshDAG() {- const newDAG = new DAGMap();- for (const [key, { value, before, after }] of this.#rawData) {- this.#addHandlingCycles(newDAG, key, value, before, after);- }- this.#dag = newDAG;- }-}diff --git a/frontend/discourse/app/lib/dag.ts b/frontend/discourse/app/lib/dag.tsnew file mode 100644index 00000000000..fc822dd2370--- /dev/null+++ b/frontend/discourse/app/lib/dag.ts@@ -0,0 +1,774 @@+import { bind } from "discourse/lib/decorators";+import { makeArray } from "discourse/lib/helpers";++/**+ * A key or array of keys used to position an item relative to others.+ */+export interface DAGPosition {+ /** A key or array of keys of items which should appear before this one. */+ before?: string | string[];+ /** A key or array of keys of items which should appear after this one. */+ after?: string | string[];+}++export interface DAGOptions<T = unknown> {+ /** Default positioning rules for new items. */+ defaultPosition?: DAGPosition;+ /**+ * Whether to throw an error when a cycle is detected. When false, the+ * default position will be used instead.+ */+ throwErrorOnCycle?: boolean;+ /** Called when an item is added. */+ onAddItem?: (key: string, value: T, position: DAGPosition) => void;+ /** Called when an item is removed. */+ onDeleteItem?: (key: string) => void;+ /** Called when an item is replaced. */+ onReplaceItem?: (+ key: string,+ newValue: T,+ oldValue: T,+ newPosition: DAGPosition | undefined,+ oldPosition: DAGPosition+ ) => void;+ /** Called when an item is repositioned. */+ onRepositionItem?: (+ key: string,+ newPosition: DAGPosition,+ oldPosition: DAGPosition+ ) => void;+}++/**+ * A resolved key/value pair together with its positioning rules, as+ * returned by {@link DAG#resolve}.+ */+export interface DAGResolvedEntry<T = unknown> {+ key: string;+ value: T;+ position: DAGPosition;+}++interface DAGItem<T> {+ value: T;+ before?: string | string[];+ after?: string | string[];+}++interface DAGVertex<T> {+ key: string;+ val: T | undefined;+ inEdges: Set<string>;+ outEdges: Set<string>;+ insertionIdx: number;++ /**+ * The before/after constraints actually applied to the graph for this+ * vertex. They can differ from the item's declared position when a+ * cycle forced a fallback to the default position, and they drive the+ * placement ranks computed by the sort.+ */+ appliedBefore?: string | string[];+ appliedAfter?: string | string[];+}++/* Placement-rank slots: a rank extended with BEFORE_ANCHOR sorts just+ before its anchor, with AFTER_ANCHOR just after it. The anchor itself+ compares as 0 (the implicit padding value in compareRanks). */+const BEFORE_ANCHOR = -1;+const AFTER_ANCHOR = 1;++/**+ * Lexicographic comparison of placement ranks. A rank that runs out of+ * elements compares as 0 from then on, ordering an anchor between its+ * before-extensions (-1, ...) and its after-extensions (1, ...).+ */+function compareRanks(a: number[], b: number[]): number {+ const len = Math.max(a.length, b.length);+ for (let i = 0; i < len; i++) {+ const av = i < a.length ? a[i] : 0;+ const bv = i < b.length ? b[i] : 0;+ if (av !== bv) {+ return av < bv ? -1 : 1;+ }+ }+ return 0;+}++/** Binary min-heap over numbers, used to pop the lowest rank ordinal. */+class MinHeap {+ #heap: number[] = [];++ get size(): number {+ return this.#heap.length;+ }++ push(value: number): void {+ const heap = this.#heap;+ heap.push(value);+ let i = heap.length - 1;+ while (i > 0) {+ const parent = Math.floor((i - 1) / 2);+ if (heap[parent] <= heap[i]) {+ break;+ }+ [heap[parent], heap[i]] = [heap[i], heap[parent]];+ i = parent;+ }+ }++ pop(): number {+ const heap = this.#heap;+ const top = heap[0];+ const last = heap.pop();+ if (heap.length > 0) {+ heap[0] = last;+ let i = 0;+ for (;;) {+ const left = 2 * i + 1;+ const right = left + 1;+ let min = i;+ if (left < heap.length && heap[left] < heap[min]) {+ min = left;+ }+ if (right < heap.length && heap[right] < heap[min]) {+ min = right;+ }+ if (min === i) {+ break;+ }+ [heap[min], heap[i]] = [heap[i], heap[min]];+ i = min;+ }+ }+ return top;+ }+}++class DAGCycleError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "DAGCycleError";+ }+}++export default class DAG<T = unknown> {+ /**+ * Creates a new DAG instance from an iterable of entries.+ *+ * @param entriesLike - An iterable of key-value-position tuples to initialize the DAG.+ * @param opts - Optional configuration object.+ * @returns A new DAG instance.+ */+ static from<T = unknown>(+ entriesLike: Iterable<[string, T, DAGPosition?]>,+ opts?: DAGOptions<T>+ ): DAG<T> {+ const dag = new this(opts) as DAG<T>;++ for (const [key, value, position] of entriesLike) {+ dag.add(key, value, position);+ }++ return dag;+ }++ #defaultPosition: DAGPosition;+ #onAddItem?: DAGOptions<T>["onAddItem"];+ #onDeleteItem?: DAGOptions<T>["onDeleteItem"];+ #onReplaceItem?: DAGOptions<T>["onReplaceItem"];+ #onRepositionItem?: DAGOptions<T>["onRepositionItem"];+ #throwErrorOnCycle: boolean;++ #items = new Map<string, DAGItem<T>>();+ #vertices = new Map<string, DAGVertex<T>>();+ #insertionCounter = 0;+ #dirty = true;+ #cachedResolve: DAGResolvedEntry<T>[] | null = null;++ /**+ * Creates a new Directed Acyclic Graph (DAG) instance.+ *+ * @param opts - Optional configuration object.+ */+ constructor(opts?: DAGOptions<T>) {+ this.#defaultPosition = opts?.defaultPosition || {};+ this.#throwErrorOnCycle = opts?.throwErrorOnCycle ?? true;++ this.#onAddItem = opts?.onAddItem;+ this.#onDeleteItem = opts?.onDeleteItem;+ this.#onReplaceItem = opts?.onReplaceItem;+ this.#onRepositionItem = opts?.onRepositionItem;+ }++ /**+ * Adds a key/value pair to the DAG. Can optionally specify before/after position requirements.+ *+ * @param key - The key of the item to be added. Can be referenced by other member's position parameters.+ * @param value - The value of the item to be added.+ * @param position - The position object specifying before/after requirements.+ * @returns True if the item was added, false if the key already exists.+ */+ add(key: string, value: T, position?: DAGPosition): boolean {+ if (this.has(key)) {+ return false;+ }++ position ||= this.#defaultPositionForKey(key);+ const { before, after } = position;++ try {+ this.#addToGraph(key, value, before, after);+ } catch (e) {+ // Roll the graph back to the current items so a failed add leaves nothing behind.+ this.#rebuildGraph();+ throw e;+ }++ this.#items.set(key, { value, before, after });+ this.#dirty = true;+ this.#onAddItem?.(key, value, position);++ return true;+ }++ /**+ * Remove an item from the map by key.+ *+ * @param key - The key of the item to be removed.+ * @returns True if the item was deleted, false otherwise.+ */+ delete(key: string): boolean {+ const deleted = this.#items.delete(key);+ if (deleted) {+ this.#dirty = true;+ this.#rebuildGraph();+ this.#onDeleteItem?.(key);+ }++ return deleted;+ }++ /**+ * Replace an existing item in the map.+ *+ * @param key - The key of the item to be replaced.+ * @param value - The new value of the item.+ * @param position - The new position constraints. If omitted, the existing position is preserved.+ * @returns True if the item was replaced, false otherwise.+ */+ replace(key: string, value: T, position?: DAGPosition): boolean {+ return this.#replace(key, value, position);+ }++ /**+ * Change the positioning rules of an existing item in the map. Will replace all existing rules.+ *+ * @param key - The key of the item to reposition.+ * @param position - The new position constraints. Replaces all existing rules.+ * @returns True if the item was repositioned, false otherwise.+ */+ reposition(key: string, position: DAGPosition): boolean {+ if (!this.has(key) || !position) {+ return false;+ }++ const { value } = this.#items.get(key);++ return this.#replace(key, value, position, { repositionOnly: true });+ }++ /**+ * Check whether an item exists in the map.+ *+ * @param key - The key to check for existence.+ * @returns True if the item exists, false otherwise.+ */+ has(key: string): boolean {+ return this.#items.has(key);+ }++ /**+ * Returns an array of entries in the DAG. Each entry is a tuple containing the key, value, and position object.+ *+ * @returns An array of key-value-position tuples.+ */+ entries(): Array<[string, T, DAGPosition]> {+ return Array.from(this.#items.entries()).map(+ ([key, { value, before, after }]) => [key, value, { before, after }]+ );+ }++ /**+ * Return the resolved key/value pairs in the map. The order of the+ * pairs is determined by the before/after rules using a+ * locality-preserving topological sort.+ *+ * The result is memoized per instance: repeated resolve() calls on an+ * unmutated DAG return the same array (helps the header icon/button+ * singletons that re-resolve on every render).+ *+ * @returns An array of key/value/position objects.+ */+ @bind+ resolve(): DAGResolvedEntry<T>[] {+ if (!this.#dirty && this.#cachedResolve) {+ return this.#cachedResolve;+ }++ const sortedKeys = this.#sort();+ const result: DAGResolvedEntry<T>[] = [];++ for (let i = 0; i < sortedKeys.length; i++) {+ const key = sortedKeys[i];+ if (this.has(key)) {+ const { value, before, after } = this.#items.get(key);+ result.push({ key, value, position: { before, after } });+ }+ }++ this.#dirty = false;+ // Frozen so callers can't mutate the shared cached array in place.+ Object.freeze(result);+ this.#cachedResolve = result;+ return result;+ }++ /* Graph management */++ /**+ * Returns the default position for a given key, excluding any+ * constraints that reference the key itself. This prevents+ * self-loops when the default position happens to mention the+ * same key being added (e.g., adding "search" with a default+ * of `{ before: "search" }` would otherwise create a self-edge).+ *+ * @param key - The key to compute the default position for.+ * @returns The default position with self-references stripped.+ */+ #defaultPositionForKey(key: string): DAGPosition {+ const pos = { ...this.#defaultPosition };+ if (makeArray(pos.before).includes(key)) {+ delete pos.before;+ }+ if (makeArray(pos.after).includes(key)) {+ delete pos.after;+ }+ return pos;+ }++ /**+ * Returns the vertex for the given key, creating a placeholder+ * vertex if one does not exist yet. Placeholder vertices support+ * forward references: a key can appear in a before/after constraint+ * before it is explicitly added via `add()`.+ *+ * @param key - The vertex key.+ * @returns The vertex object.+ */+ #getOrCreateVertex(key: string): DAGVertex<T> {+ let v = this.#vertices.get(key);+ if (v === undefined) {+ v = {+ key,+ val: undefined,+ inEdges: new Set(),+ outEdges: new Set(),+ insertionIdx: -1,+ };+ this.#vertices.set(key, v);+ }+ return v;+ }++ /**+ * Adds a vertex and its edges to the internal graph. When+ * `throwErrorOnCycle` is false, a cycle caused by the requested+ * position will be caught and the item will be re-added using+ * the default position instead.+ *+ * @param key - The vertex key.+ * @param value - The vertex value.+ * @param before - Key(s) this vertex must appear before.+ * @param after - Key(s) this vertex must appear after.+ */+ #addToGraph(+ key: string,+ value: T,+ before?: string | string[],+ after?: string | string[]+ ): void {+ if (this.#throwErrorOnCycle) {+ this.#addVertexAndEdges(key, value, before, after);+ } else {+ try {+ this.#addVertexAndEdges(key, value, before, after);+ } catch (e) {+ if (!(e instanceof DAGCycleError)) {+ throw e;+ }+ const { before: newBefore, after: newAfter } =+ this.#defaultPositionForKey(key);+ try {+ this.#addVertexAndEdges(key, value, newBefore, newAfter);+ } catch (e2) {+ if (!(e2 instanceof DAGCycleError)) {+ throw e2;+ }+ // Both the requested and default positions create a cycle.+ // The vertex exists but has no constraint edges.+ }+ }+ }+ }++ #addVertexAndEdges(+ key: string,+ value: T,+ before?: string | string[],+ after?: string | string[]+ ): void {+ const v = this.#getOrCreateVertex(key);+ v.val = value;+ if (v.insertionIdx === -1) {+ v.insertionIdx = this.#insertionCounter++;+ }++ // Track edges added during this call as [fromKey, toKey] pairs+ // so they can be rolled back if a later constraint creates a cycle.+ const added: string[] = [];++ try {+ if (before) {+ if (typeof before === "string") {+ if (this.#addEdge(v, this.#getOrCreateVertex(before))) {+ added.push(v.key, before);+ }+ } else {+ for (let i = 0; i < before.length; i++) {+ if (this.#addEdge(v, this.#getOrCreateVertex(before[i]))) {+ added.push(v.key, before[i]);+ }+ }+ }+ }++ if (after) {+ if (typeof after === "string") {+ if (this.#addEdge(this.#getOrCreateVertex(after), v)) {+ added.push(after, v.key);+ }+ } else {+ for (let i = 0; i < after.length; i++) {+ if (this.#addEdge(this.#getOrCreateVertex(after[i]), v)) {+ added.push(after[i], v.key);+ }+ }+ }+ }+ } catch (e) {+ for (let i = 0; i < added.length; i += 2) {+ this.#vertices.get(added[i]).outEdges.delete(added[i + 1]);+ this.#vertices.get(added[i + 1]).inEdges.delete(added[i]);+ }+ throw e;+ }++ // Recorded only on success so a cycle fallback re-records the+ // constraints that actually made it into the graph.+ v.appliedBefore = before;+ v.appliedAfter = after;+ }++ #addEdge(from: DAGVertex<T>, to: DAGVertex<T>): boolean {+ if (from.key === to.key) {+ throw new DAGCycleError("cycle detected: " + to.key + " <- " + to.key);+ }++ if (from.outEdges.has(to.key)) {+ return false;+ }++ if (to.outEdges.size > 0) {+ const path = this.#findCyclePath(to, from.key);+ if (path !== null) {+ throw new DAGCycleError("cycle detected: " + path);+ }+ }++ from.outEdges.add(to.key);+ to.inEdges.add(from.key);+ return true;+ }++ #findCyclePath(start: DAGVertex<T>, targetKey: string): string | null {+ if (start.outEdges.has(targetKey)) {+ return targetKey + " <- " + start.key + " <- " + targetKey;+ }++ const visited = new Set([start.key]);+ const parent = new Map<string, string>();+ const frontier: string[] = [];++ for (const next of start.outEdges) {+ if (!visited.has(next)) {+ visited.add(next);+ parent.set(next, start.key);+ frontier.push(next);+ }+ }++ for (let head = 0; head < frontier.length; head++) {+ const key = frontier[head];++ if (key === targetKey) {+ let msg = targetKey;+ let cur: string | undefined = targetKey;+ while (cur !== undefined) {+ msg += " <- " + (parent.get(cur) ?? start.key);+ cur = parent.get(cur);+ if (cur === start.key) {+ break;+ }+ }+ msg += " <- " + targetKey;+ return msg;+ }++ const vertex = this.#vertices.get(key);+ if (vertex) {+ for (const next of vertex.outEdges) {+ if (!visited.has(next)) {+ visited.add(next);+ parent.set(next, key);+ frontier.push(next);+ }+ }+ }+ }++ return null;+ }++ #rebuildGraph(): void {+ this.#vertices = new Map();+ this.#insertionCounter = 0;+ for (const [key, { value, before, after }] of this.#items) {+ this.#addToGraph(key, value, before, after);+ }+ }++ #replace(+ key: string,+ value: T,+ position?: DAGPosition,+ { repositionOnly }: { repositionOnly: boolean } = { repositionOnly: false }+ ): boolean {+ if (!this.has(key)) {+ return false;+ }++ const existingItem = this.#items.get(key);+ const oldValue = existingItem.value;+ const oldPosition = {+ before: existingItem.before,+ after: existingItem.after,+ };++ existingItem.value = value;++ if (position) {+ existingItem.before = position.before;+ existingItem.after = position.after;+ }++ this.#dirty = true;++ try {+ this.#rebuildGraph();+ } catch (e) {+ existingItem.value = oldValue;+ existingItem.before = oldPosition.before;+ existingItem.after = oldPosition.after;+ this.#rebuildGraph();+ throw e;+ }++ if (repositionOnly) {+ this.#onRepositionItem?.(key, position, oldPosition);+ } else {+ this.#onReplaceItem?.(key, value, oldValue, position, oldPosition);+ }++ return true;+ }++ /* Sorting */++ /**+ * Locality-preserving topological sort.+ *+ * Every vertex gets a placement rank, and the output is the topological+ * order closest to rank order: Kahn's algorithm always emits the+ * lowest-ranked ready vertex, so the result deviates from rank order+ * only where an edge contradicts it, and only for the vertices that+ * edge touches. The output is always a valid topological order.+ *+ * A rank is a path of `(side, insertionIdx)` steps rooted at an+ * unanchored vertex. Each vertex anchors to at most ONE key from its+ * applied position — the anchor decides where the vertex prefers to+ * sit, while every declared key remains a hard ordering edge:+ *+ * - `after: X` extends X's rank on the after side: the item sorts+ * immediately after X (and after X's whole after-group, in insertion+ * order), before anything unrelated to X.+ * - `before: X` extends X's rank on the before side: the item sorts+ * immediately before X, again in insertion order within the group.+ * - With both `before` and `after`, the `after` anchor wins: the item+ * hugs the item it follows.+ * - With multiple keys on one side, `after` anchors to the+ * highest-ranked key and `before` to the lowest-ranked one — the+ * nearest end of the window the constraints allow.+ * - Anchors never added to the DAG are ignored (an item constrained+ * only relative to absent keys ranks by its own insertion index, and+ * an absent key itself sorts past every real item, so anything+ * `after` it lands at the end). Mutually recursive anchor references+ * (e.g. `x after a` + `a before x`) break the loop at the vertex+ * reached last, which then ranks by insertion index.+ */+ #sort(): string[] {+ const vertices = this.#vertices;+ const size = vertices.size;+ if (size === 0) {+ return [];+ }++ const sortedKeys = this.#keysInRankOrder();+ const ordinals = new Map<string, number>();+ for (let i = 0; i < sortedKeys.length; i++) {+ ordinals.set(sortedKeys[i], i);+ }++ const inDegree = new Map<string, number>();+ const ready = new MinHeap();+ for (const [key, v] of vertices) {+ inDegree.set(key, v.inEdges.size);+ if (v.inEdges.size === 0) {+ ready.push(ordinals.get(key));+ }+ }++ const result: string[] = [];+ while (ready.size > 0) {+ const key = sortedKeys[ready.pop()];+ result.push(key);++ for (const succKey of vertices.get(key).outEdges) {+ const d = inDegree.get(succKey) - 1;+ inDegree.set(succKey, d);+ if (d === 0) {+ ready.push(ordinals.get(succKey));+ }+ }+ }++ if (result.length !== size) {+ const remaining: string[] = [];+ for (const [key, deg] of inDegree) {+ if (deg > 0) {+ remaining.push(key);+ }+ }+ throw new DAGCycleError(+ "cycle detected among: " + JSON.stringify(remaining)+ );+ }++ return result;+ }++ #keysInRankOrder(): string[] {+ const ranks = this.#computeRanks();+ const keys = [...this.#vertices.keys()];+ keys.sort((a, b) => compareRanks(ranks.get(a), ranks.get(b)));+ return keys;+ }++ /**+ * Computes the placement rank of every vertex (see the sort method's+ * doc for the rank semantics).+ * Memoized per call; anchor chains are followed recursively with an+ * in-progress guard so mutually recursive anchor references terminate.+ */+ #computeRanks(): Map<string, number[]> {+ const ranks = new Map<string, number[]>();+ const inProgress = new Set<string>();++ const selectAnchor = (+ refs: string | string[] | undefined,+ latest: boolean+ ): string | null => {+ if (!refs) {+ return null;+ }++ let best: string | null = null;+ let bestRank: number[] | null = null;++ for (const ref of makeArray(refs)) {+ const anchor = this.#vertices.get(ref);+ if (!anchor || anchor.insertionIdx === -1 || inProgress.has(ref)) {+ continue;+ }++ const anchorRank = rankOf(ref);+ if (+ best === null ||+ (latest+ ? compareRanks(anchorRank, bestRank) > 0+ : compareRanks(anchorRank, bestRank) < 0)+ ) {+ best = ref;+ bestRank = anchorRank;+ }+ }++ return best;+ };++ const rankOf = (key: string): number[] => {+ let rank = ranks.get(key);+ if (rank !== undefined) {+ return rank;+ }++ const v = this.#vertices.get(key);+ // Placeholder vertices (referenced but never added) sort past every+ // real insertion index.+ const idx = v.insertionIdx === -1 ? Infinity : v.insertionIdx;++ inProgress.add(key);++ const afterAnchor = selectAnchor(v.appliedAfter, true);+ if (afterAnchor !== null) {+ rank = [...rankOf(afterAnchor), AFTER_ANCHOR, idx];+ } else {+ const beforeAnchor = selectAnchor(v.appliedBefore, false);+ rank =+ beforeAnchor !== null+ ? [...rankOf(beforeAnchor), BEFORE_ANCHOR, idx]+ : [idx];+ }++ inProgress.delete(key);+ ranks.set(key, rank);+ return rank;+ };++ for (const key of this.#vertices.keys()) {+ rankOf(key);+ }++ return ranks;+ }+}diff --git a/frontend/discourse/tests/unit/lib/dag-test.js b/frontend/discourse/tests/unit/lib/dag-test.jsdeleted file mode 100644index b6db15e0c0b..00000000000--- a/frontend/discourse/tests/unit/lib/dag-test.js+++ /dev/null@@ -1,300 +0,0 @@-import { setupTest } from "ember-qunit";-import { module, test } from "qunit";-import DAG from "discourse/lib/dag";--module("Unit | Lib | DAG", function (hooks) {- setupTest(hooks);-- test("DAG.from creates a DAG instance from the provided entries", function (assert) {- const dag = DAG.from([- ["key1", "value1", { after: "key2" }],- ["key2", "value2", { before: "key3" }],- ["key3", "value3", { before: "key1" }],- ]);-- assert.true(dag.has("key1"));- assert.true(dag.has("key2"));- assert.true(dag.has("key3"));-- const resolved = dag.resolve();- const keys = resolved.map((entry) => entry.key);-- assert.deepEqual(keys, ["key2", "key3", "key1"]);- });-- test("adds items to the map", function (assert) {- const dag = new DAG();- dag.add("key1", "value1");- dag.add("key2", "value2");- dag.add("key3", "value3");-- assert.true(dag.has("key1"));- assert.true(dag.has("key2"));- assert.true(dag.has("key3"));-- // adding a new item- assert.true(- dag.add("key4", "value4"),- "adding an item returns true when the item is added"- );- assert.true(dag.has("key4"));-- // adding an item that already exists- assert.false(- dag.add("key1", "value1"),- "adding an item returns false when the item already exists"- );- });-- test("does not throw an error when throwErrorOnCycle is false when adding an item creates a cycle", function (assert) {- const dag = new DAG({- throwErrorOnCycle: false,- defaultPosition: { before: "key3" },- });-- dag.add("key1", "value1", { after: "key2" });- dag.add("key2", "value2", { after: "key3" });-- // This would normally cause a cycle if throwErrorOnCycle was true- dag.add("key3", "value3", { after: "key1" });-- assert.true(dag.has("key1"));- assert.true(dag.has("key2"));- assert.true(dag.has("key3"));-- const resolved = dag.resolve();- const keys = resolved.map((entry) => entry.key);-- // Check that the default position was used to avoid the cycle- assert.deepEqual(keys, ["key3", "key2", "key1"]);- });-- test("calls the method specified for onAddItem callback when an item is added", function (assert) {- let called = 0;-- const dag = new DAG({- onAddItem: () => {- called++;- },- });- dag.add("key1", "value1");- assert.strictEqual(called, 1, "the callback was called");-- // it doesn't call the callback when the item already exists- dag.add("key1", "value1");- assert.strictEqual(called, 1, "the callback was not called");- });-- test("removes an item from the map", function (assert) {- const dag = new DAG();- dag.add("key1", "value1");- dag.add("key2", "value2");- dag.add("key3", "value3");-- let removed = dag.delete("key2");-- assert.true(dag.has("key1"));- assert.false(dag.has("key2"));- assert.true(dag.has("key3"));-- assert.true(removed, "delete returns true when the item is removed");-- removed = dag.delete("key2");- assert.false(removed, "delete returns false when the item doesn't exist");- });-- test("calls the method specified for onDeleteItem callback when an item is removed", function (assert) {- let called = 0;-- const dag = new DAG({- onDeleteItem: () => {- called++;- },- });- dag.add("key1", "value1");- dag.delete("key1");- assert.strictEqual(called, 1, "the callback was called");-- // it doesn't call the callback when the item doesn't exist- dag.delete("key1");- assert.strictEqual(called, 1, "the callback was not called");- });-- test("replaces the value from an item in the map", function (assert) {- const dag = new DAG();- dag.add("key1", "value1");- dag.add("key2", "value2");- dag.add("key3", "value3");-- // simply replacing the value- let replaced = dag.replace("key2", "replaced-value2");-- assert.deepEqual(- dag.resolve().map((entry) => entry.value),- ["value1", "replaced-value2", "value3"],- "replace allows simply replacing the value"- );- assert.true(replaced, "replace returns true when the item is replaced");-- // also changing the position- dag.replace("key2", "replaced-value2-again", { before: "key1" });-- assert.deepEqual(- dag.resolve().map((entry) => entry.value),- ["replaced-value2-again", "value1", "value3"],- "replace also allows changing the position"- );-- // replacing an item that doesn't exist- replaced = dag.replace("key4", "replaced-value4");- assert.false(replaced, "replace returns false when the item doesn't exist");- });-- test("calls the method specified for onReplaceItem callback when an item is replaced", function (assert) {- let called = 0;-- const dag = new DAG({- onReplaceItem: () => {- called++;- },- });- dag.add("key1", "value1");- dag.replace("key1", "replaced-value1");- assert.strictEqual(called, 1, "the callback was called");-- // it doesn't call the callback when the item doesn't exist- dag.replace("key2", "replaced-value2");- assert.strictEqual(called, 1, "the callback was not called");- });-- test("repositions an item in the map", function (assert) {- const dag = new DAG();- dag.add("key1", "value1");- dag.add("key2", "value2");- dag.add("key3", "value3");-- let repositioned = dag.reposition("key3", { before: "key1" });- assert.true(- repositioned,- "reposition returns true when the item is repositioned"- );-- const resolved = dag.resolve();- const keys = resolved.map((entry) => entry.key);-- assert.deepEqual(keys, ["key3", "key1", "key2"]);-- // repositioning an item that doesn't exist- repositioned = dag.reposition("key4", { before: "key1" });- assert.false(- repositioned,- "reposition returns false when the item doesn't exist"- );- });-- test("calls the method specified for onRepositionItem callback when an item is repositioned", function (assert) {- let called = 0;-- const dag = new DAG({- onRepositionItem: () => {- called++;- },- });- dag.add("key1", "value1");- dag.reposition("key1", { before: "key2" });- assert.strictEqual(called, 1, "the callback was called");-- // it doesn't call the callback when the item doesn't exist- dag.reposition("key2", { before: "key1" });- assert.strictEqual(called, 1, "the callback was not called");- });-- test("returns the entries in the map", function (assert) {- const entries = [- ["key1", "value1", { after: "key2" }],- ["key2", "value2", { before: "key3" }],- ["key3", "value3", { before: "key1" }],- ];-- const dag = DAG.from(entries);- const dagEntries = dag.entries();-- entries.forEach((entry, index) => {- assert.strictEqual(dagEntries[index][0], entry[0], "the key is correct");- assert.strictEqual(- dagEntries[index][1],- entry[1],- "the value is correct"- );- assert.strictEqual(- dagEntries[index][2]["before"],- entry[2]["before"],- "the before position is correct"- );- assert.strictEqual(- dagEntries[index][2]["after"],- entry[2]["after"],- "the after position is correct"- );- });- });-- test("resolves the map in the correct order", function (assert) {- const dag = new DAG();- dag.add("key1", "value1");- dag.add("key2", "value2");- dag.add("key3", "value3");-- const resolved = dag.resolve();- const keys = resolved.map((entry) => entry.key);-- assert.deepEqual(keys, ["key1", "key2", "key3"]);- });-- test("allows for custom before and after default positioning", function (assert) {- const dag = new DAG({ defaultPosition: { before: "key3", after: "key2" } });- dag.add("key1", "value1", {});- dag.add("key2", "value2", { after: "key1" });- dag.add("key3", "value3", { after: "key2" });- dag.add("key4", "value4");-- const resolved = dag.resolve();- const keys = resolved.map((entry) => entry.key);-- assert.deepEqual(keys, ["key1", "key2", "key4", "key3"]);-- // it also returns the positioning data for each entry- assert.deepEqual(- resolved.map((entry) => entry.position),- [- { before: undefined, after: undefined }, // {} from key1- { before: undefined, after: "key1" }, // from key2- { before: "key3", after: "key2" }, // from the defaultPosition applied to key4- { before: undefined, after: "key2" }, // from key3- ]- );- });-- test("resolves only existing keys", function (assert) {- const dag = new DAG();- dag.add("key1", "value1");- dag.add("key2", "value2", { before: "key1" });- dag.add("key3", "value3");-- dag.delete("key1");-- const resolved = dag.resolve();- const keys = resolved.map((entry) => entry.key);-- assert.deepEqual(keys, ["key2", "key3"]);- });-- test("throws on bad positioning", function (assert) {- const dag = new DAG();-- assert.throws(- () => dag.add("key1", "value1", { before: "key1" }),- /cycle detected/- );- });-});diff --git a/frontend/discourse/tests/unit/lib/dag-test.ts b/frontend/discourse/tests/unit/lib/dag-test.tsnew file mode 100644index 00000000000..b1c3b08e36d--- /dev/null+++ b/frontend/discourse/tests/unit/lib/dag-test.ts@@ -0,0 +1,1305 @@+import { setupTest } from "ember-qunit";+import { module, test } from "qunit";+import DAG, { type DAGPosition } from "discourse/lib/dag";++function resolveKeys(dag: DAG) {+ return dag.resolve().map((entry) => entry.key);+}++/**+ * Options matching the surfaces that point their default position at a+ * single key, which gives that key an in-degree equal to the item count.+ */+function hubOptions() {+ return { defaultPosition: { before: "hub" }, throwErrorOnCycle: false };+}++/** Three items before the hub plus one after it, in registration order. */+function addHubGroup(dag: DAG) {+ dag.add("first", 1, { before: ["hub"] });+ dag.add("second", 2, { before: ["hub"] });+ dag.add("third", 3, { before: ["hub"] });+ dag.add("hub", 4, {});+ dag.add("trailing", 5, { after: ["hub"] });+}++module("Unit | Lib | DAG", function (hooks) {+ setupTest(hooks);++ /* Core API */++ test("DAG.from creates a DAG instance from the provided entries", function (assert) {+ const dag = DAG.from([+ ["key1", "value1", { after: "key2" }],+ ["key2", "value2", { before: "key3" }],+ ["key3", "value3", { before: "key1" }],+ ]);++ assert.true(dag.has("key1"));+ assert.true(dag.has("key2"));+ assert.true(dag.has("key3"));++ const resolved = dag.resolve();+ const keys = resolved.map((entry) => entry.key);++ assert.deepEqual(keys, ["key2", "key3", "key1"]);+ });++ test("adds items to the map", function (assert) {+ const dag = new DAG();+ dag.add("key1", "value1");+ dag.add("key2", "value2");+ dag.add("key3", "value3");++ assert.true(dag.has("key1"));+ assert.true(dag.has("key2"));+ assert.true(dag.has("key3"));++ assert.true(+ dag.add("key4", "value4"),+ "adding an item returns true when the item is added"+ );+ assert.true(dag.has("key4"));++ assert.false(+ dag.add("key1", "value1"),+ "adding an item returns false when the item already exists"+ );+ });++ test("does not throw an error when throwErrorOnCycle is false when adding an item creates a cycle", function (assert) {+ const dag = new DAG({+ throwErrorOnCycle: false,+ defaultPosition: { before: "key3" },+ });++ dag.add("key1", "value1", { after: "key2" });+ dag.add("key2", "value2", { after: "key3" });++ // This would normally cause a cycle if throwErrorOnCycle was true+ dag.add("key3", "value3", { after: "key1" });++ assert.true(dag.has("key1"));+ assert.true(dag.has("key2"));+ assert.true(dag.has("key3"));++ const resolved = dag.resolve();+ const keys = resolved.map((entry) => entry.key);++ // Check that the default position was used to avoid the cycle+ assert.deepEqual(keys, ["key3", "key2", "key1"]);+ });++ test("calls the method specified for onAddItem callback when an item is added", function (assert) {+ let called = 0;++ const dag = new DAG({+ onAddItem: () => {+ called++;+ },+ });+ dag.add("key1", "value1");+ assert.strictEqual(called, 1, "the callback was called");++ // it doesn't call the callback when the item already exists+ dag.add("key1", "value1");+ assert.strictEqual(called, 1, "the callback was not called");+ });++ test("removes an item from the map", function (assert) {+ const dag = new DAG();+ dag.add("key1", "value1");+ dag.add("key2", "value2");+ dag.add("key3", "value3");++ let removed = dag.delete("key2");++ assert.true(dag.has("key1"));+ assert.false(dag.has("key2"));+ assert.true(dag.has("key3"));++ assert.true(removed, "delete returns true when the item is removed");++ removed = dag.delete("key2");+ assert.false(removed, "delete returns false when the item doesn't exist");+ });++ test("calls the method specified for onDeleteItem callback when an item is removed", function (assert) {+ let called = 0;++ const dag = new DAG({+ onDeleteItem: () => {+ called++;+ },+ });+ dag.add("key1", "value1");+ dag.delete("key1");+ assert.strictEqual(called, 1, "the callback was called");++ // it doesn't call the callback when the item doesn't exist+ dag.delete("key1");+ assert.strictEqual(called, 1, "the callback was not called");+ });++ test("replaces the value from an item in the map", function (assert) {+ const dag = new DAG();+ dag.add("key1", "value1");+ dag.add("key2", "value2");+ dag.add("key3", "value3");++ let replaced = dag.replace("key2", "replaced-value2");++ assert.deepEqual(+ dag.resolve().map((entry) => entry.value),+ ["value1", "replaced-value2", "value3"],+ "replace allows simply replacing the value"+ );+ assert.true(replaced, "replace returns true when the item is replaced");++ dag.replace("key2", "replaced-value2-again", { before: "key1" });++ assert.deepEqual(+ dag.resolve().map((entry) => entry.value),+ ["replaced-value2-again", "value1", "value3"],+ "replace also allows changing the position"+ );++ replaced = dag.replace("key4", "replaced-value4");+ assert.false(replaced, "replace returns false when the item doesn't exist");+ });++ test("calls the method specified for onReplaceItem callback when an item is replaced", function (assert) {+ let called = 0;++ const dag = new DAG({+ onReplaceItem: () => {+ called++;+ },+ });+ dag.add("key1", "value1");+ dag.replace("key1", "replaced-value1");+ assert.strictEqual(called, 1, "the callback was called");++ dag.replace("key2", "replaced-value2");+ assert.strictEqual(called, 1, "the callback was not called");+ });++ test("repositions an item in the map", function (assert) {+ const dag = new DAG();+ dag.add("key1", "value1");+ dag.add("key2", "value2");+ dag.add("key3", "value3");++ let repositioned = dag.reposition("key3", { before: "key1" });+ assert.true(+ repositioned,+ "reposition returns true when the item is repositioned"+ );++ const resolved = dag.resolve();+ const keys = resolved.map((entry) => entry.key);++ assert.deepEqual(keys, ["key3", "key1", "key2"]);++ repositioned = dag.reposition("key4", { before: "key1" });+ assert.false(+ repositioned,+ "reposition returns false when the item doesn't exist"+ );+ });++ test("calls the method specified for onRepositionItem callback when an item is repositioned", function (assert) {+ let called = 0;++ const dag = new DAG({+ onRepositionItem: () => {+ called++;+ },+ });+ dag.add("key1", "value1");+ dag.reposition("key1", { before: "key2" });+ assert.strictEqual(called, 1, "the callback was called");++ dag.reposition("key2", { before: "key1" });+ assert.strictEqual(called, 1, "the callback was not called");+ });++ test("returns the entries in the map", function (assert) {+ const entries: Array<[string, string, DAGPosition]> = [+ ["key1", "value1", { after: "key2" }],+ ["key2", "value2", { before: "key3" }],+ ["key3", "value3", { before: "key1" }],+ ];++ const dag = DAG.from(entries);+ const dagEntries = dag.entries();++ entries.forEach((entry, index) => {+ assert.strictEqual(dagEntries[index][0], entry[0], "the key is correct");+ assert.strictEqual(+ dagEntries[index][1],+ entry[1],+ "the value is correct"+ );+ assert.strictEqual(+ dagEntries[index][2]["before"],+ entry[2]["before"],+ "the before position is correct"+ );+ assert.strictEqual(+ dagEntries[index][2]["after"],+ entry[2]["after"],+ "the after position is correct"+ );+ });+ });++ test("resolves the map in the correct order", function (assert) {+ const dag = new DAG();+ dag.add("key1", "value1");+ dag.add("key2", "value2");+ dag.add("key3", "value3");++ const resolved = dag.resolve();+ const keys = resolved.map((entry) => entry.key);++ assert.deepEqual(keys, ["key1", "key2", "key3"]);+ });++ test("allows for custom before and after default positioning", function (assert) {+ const dag = new DAG({ defaultPosition: { before: "key3", after: "key2" } });+ dag.add("key1", "value1", {});+ dag.add("key2", "value2", { after: "key1" });+ dag.add("key3", "value3", { after: "key2" });+ dag.add("key4", "value4");++ const resolved = dag.resolve();+ const keys = resolved.map((entry) => entry.key);++ assert.deepEqual(keys, ["key1", "key2", "key4", "key3"]);++ assert.deepEqual(+ resolved.map((entry) => entry.position),+ [+ { before: undefined, after: undefined },+ { before: undefined, after: "key1" },+ { before: "key3", after: "key2" },+ { before: undefined, after: "key2" },+ ]+ );+ });++ test("resolves only existing keys", function (assert) {+ const dag = new DAG();+ dag.add("key1", "value1");+ dag.add("key2", "value2", { before: "key1" });+ dag.add("key3", "value3");++ dag.delete("key1");++ const resolved = dag.resolve();+ const keys = resolved.map((entry) => entry.key);++ assert.deepEqual(keys, ["key2", "key3"]);+ });++ test("throws on bad positioning", function (assert) {+ const dag = new DAG();++ assert.throws(+ () => dag.add("key1", "value1", { before: "key1" }),+ /cycle detected/+ );+ });++ test("add() that throws on a cycle does not leave the item behind", function (assert) {+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });++ // Closes a cycle (a -> b -> c -> a), so the add throws. A caller that+ // catches the throw expects "c" to be absent, not silently present and+ // mispositioned in resolve().+ assert.throws(+ () => dag.add("c", 3, { before: "a", after: "b" }),+ /cycle detected/+ );++ assert.false(dag.has("c"), "the item is not present after a failed add");+ assert.deepEqual(+ resolveKeys(dag),+ ["a", "b"],+ "resolve() does not include the item whose add threw"+ );+ });++ test("throwErrorOnCycle false: stale edges cleaned up on array constraint cycle", function (assert) {+ // When a before/after array partially applies (some edges succeed,+ // then a later one cycles), the successful edges must be rolled+ // back before retrying with the default position.+ const dag = new DAG({+ throwErrorOnCycle: false,+ defaultPosition: { before: "end" },+ });+ dag.add("start", 1);+ dag.add("middle", 2, { after: "start" });+ dag.add("end", 3, { after: "middle" });++ // "trouble" tries before:["start","middle"] + after:"end".+ // before-start and before-middle edges are added, then after-end+ // creates a cycle (end -> trouble -> start -> middle -> end).+ // Without rollback, the stale before-start and before-middle+ // edges push trouble to the very beginning of the sort.+ dag.add("trouble", 4, { before: ["start", "middle"], after: "end" });++ // With rollback: trouble gets default { before: "end" }, placing+ // it between middle and end.+ assert.deepEqual(resolveKeys(dag), ["start", "middle", "trouble", "end"]);+ });++ test("throwErrorOnCycle false: graceful fallback when default position also cycles", function (assert) {+ // When the original position cycles and the default position also+ // cycles, the item should be added with no constraints rather+ // than throwing.+ const dag = new DAG({+ throwErrorOnCycle: false,+ defaultPosition: { before: "base" },+ });+ dag.add("base", 1);+ // mid's { before: "trouble" } creates an edge mid->trouble,+ // giving trouble an inEdge before it is explicitly added.+ dag.add("mid", 2, { after: "base", before: "trouble" });++ // trouble tries { before: "base" } which cycles (base->mid->trouble->base).+ // Default { before: "base" } also cycles (same path).+ // Should gracefully add with no constraints.+ dag.add("trouble", 3, { after: "mid", before: "base" });++ assert.true(dag.has("trouble"), "trouble was added despite double cycle");++ // trouble still appears after mid because of mid's { before: "trouble" }+ assert.deepEqual(resolveKeys(dag), ["base", "mid", "trouble"]);+ });++ test("resolve returns cached result when DAG is not mutated", function (assert) {+ // Instance-level cache: repeated resolve() calls on the same+ // unmutated DAG return the exact same array reference.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });++ const first = dag.resolve();+ const second = dag.resolve();+ assert.strictEqual(first, second, "same reference on repeated resolve()");++ // Mutation invalidates the cache+ dag.add("c", 3);+ const third = dag.resolve();+ assert.notStrictEqual(first, third, "new reference after mutation");+ });++ test("cycle fallback uses each DAG's own defaultPosition", function (assert) {+ // Two DAGs with the same items but a different defaultPosition resolve+ // the same cycle to different orders, each using its own fallback.+ const items: Array<[string, string, DAGPosition]> = [+ ["a", "a", { after: "b" }],+ ["b", "b", { after: "a" }], // cycle a <-> b+ ["c", "c", {}],+ ];++ const first = DAG.from(items, {+ throwErrorOnCycle: false,+ defaultPosition: { before: "c" },+ });+ assert.deepEqual(+ resolveKeys(first),+ ["b", "a", "c"],+ "first DAG resolves the cycle using its own defaultPosition"+ );++ const second = DAG.from(items, {+ throwErrorOnCycle: false,+ defaultPosition: { after: "c" },+ });+ assert.deepEqual(+ resolveKeys(second),+ ["c", "b", "a"],+ "second DAG uses its own defaultPosition"+ );+ });++ test("resolve() returns a frozen array", function (assert) {+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2);++ const resolved = dag.resolve();++ assert.true(Object.isFrozen(resolved), "the resolved array is frozen");+ assert.throws(+ () => resolved.push({ key: "c", value: 3, position: {} }),+ /extensible/,+ "mutating the resolved array throws"+ );+ });++ /* after locality */++ test("single after: item placed immediately after anchor", function (assert) {+ // b { after: a } => a, b with no gap between them.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });++ assert.deepEqual(resolveKeys(dag), ["a", "b"]);+ });++ test("after chain stays together", function (assert) {+ // a->b->c forms a chain. Anchoring is recursive, so each link+ // ranks immediately after its predecessor.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });+ dag.add("c", 3, { after: "b" });++ assert.deepEqual(resolveKeys(dag), ["a", "b", "c"]);+ });++ test("after chain with branch: chain stays together, branch at end", function (assert) {+ // Both b and c depend on a. b also has a successor d.+ // d nests inside b's group, and b outranks c by registration+ // order, so the a->b->d chain comes before c.+ //+ // a -> b -> d+ // \-> c+ //+ // Expected: a, b, d, c+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });+ dag.add("c", 3, { after: "a" });+ dag.add("d", 4, { after: "b" });++ assert.deepEqual(+ resolveKeys(dag),+ ["a", "b", "d", "c"],+ "A->B->D chain together, then C"+ );+ });++ test("multiple items after same anchor: grouped in insertion order", function (assert) {+ // Three items all say { after: "anchor" }. They all become ready+ // when anchor is placed, and are visited in insertion order.+ //+ // Expected: anchor, first, second, third+ const dag = new DAG();+ dag.add("anchor", 0);+ dag.add("first", 1, { after: "anchor" });+ dag.add("second", 2, { after: "anchor" });+ dag.add("third", 3, { after: "anchor" });++ const result = resolveKeys(dag);+ assert.strictEqual(result[0], "anchor");+ assert.deepEqual(result.slice(1), ["first", "second", "third"]);+ });++ test("unrelated items do not drift between anchor and after items", function (assert) {+ // "unrelated" has no constraints. Without locality, a naive sort+ // could place it between a and b. Anchored items rank right next+ // to their anchor, keeping a->b together.+ //+ // Expected: a, b, unrelated+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });+ dag.add("unrelated", 3);++ assert.deepEqual(+ resolveKeys(dag),+ ["a", "b", "unrelated"],+ "unrelated goes after the a->b pair"+ );+ });++ /* before locality */++ test("single before: item placed immediately before target", function (assert) {+ // b { before: a } => b, a with no gap.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { before: "a" });++ assert.deepEqual(resolveKeys(dag), ["b", "a"]);+ });++ test("multiple items before same target: grouped in insertion order", function (assert) {+ // Both first and second say { before: "target" }. They share the+ // same anchor side, so they rank consecutively before target in+ // registration order.+ //+ // Expected: first, second, target+ const dag = new DAG();+ dag.add("target", 0);+ dag.add("first", 1, { before: "target" });+ dag.add("second", 2, { before: "target" });++ const result = resolveKeys(dag);+ const targetIdx = result.indexOf("target");++ assert.true(result.indexOf("first") < targetIdx, "first is before target");+ assert.true(+ result.indexOf("second") < targetIdx,+ "second is before target"+ );+ assert.strictEqual(+ targetIdx,+ result.length - 1,+ "target is last (all predecessors before it)"+ );+ });++ test("unrelated items do not drift between before items and target", function (assert) {+ // b and c both say { before: a }. "unrelated" has no constraints.+ // A naive insertion-order sort would place "unrelated" between the+ // before-items and their target; anchoring ranks b and c right+ // before a instead, keeping unrelated at the end.+ //+ // Expected: b, c, a, unrelated+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { before: "a" });+ dag.add("unrelated", 3);+ dag.add("c", 4, { before: "a" });++ const result = resolveKeys(dag);+ const aIdx = result.indexOf("a");++ assert.true(result.indexOf("b") < aIdx, "b is before a");+ assert.true(result.indexOf("c") < aIdx, "c is before a");+ assert.true(+ result.indexOf("unrelated") > aIdx,+ "unrelated does not drift between before-items and target"+ );+ });++ test("before with many predecessors and unrelated items", function (assert) {+ // p1, p2, p3 all say { before: "target" }. "unrelated" sits+ // between p1 and p2 in insertion order, but the anchored items+ // are grouped right before target, pushing unrelated to the end.+ //+ // Expected: p1, p2, p3, target, unrelated+ const dag = new DAG();+ dag.add("target", 0);+ dag.add("p1", 1, { before: "target" });+ dag.add("unrelated", 2);+ dag.add("p2", 3, { before: "target" });+ dag.add("p3", 4, { before: "target" });++ const result = resolveKeys(dag);+ const targetIdx = result.indexOf("target");++ assert.true(result.indexOf("p1") < targetIdx, "p1 before target");+ assert.true(result.indexOf("p2") < targetIdx, "p2 before target");+ assert.true(result.indexOf("p3") < targetIdx, "p3 before target");+ assert.true(+ result.indexOf("unrelated") > targetIdx,+ "unrelated after target, not between predecessors"+ );+ });++ /* Mixed constraints */++ test("before and after on the same node", function (assert) {+ // c says { before: b, after: a }, so c must appear between a and b.+ //+ // Expected: a, c, b+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2);+ dag.add("c", 3, { before: "b", after: "a" });++ assert.deepEqual(+ resolveKeys(dag),+ ["a", "c", "b"],+ "c is after a and before b"+ );+ });++ test("diamond pattern", function (assert) {+ // Classic diamond: a at the top, b and c in the middle, d at+ // the bottom depending on both b and c.+ //+ // a -> b -> d+ // \-> c -/+ //+ // Expected: a first, d last, b and c in between.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });+ dag.add("c", 3, { after: "a" });+ dag.add("d", 4, { after: ["b", "c"] });++ const result = resolveKeys(dag);+ assert.strictEqual(result[0], "a", "a is first");+ assert.strictEqual(result[result.length - 1], "d", "d is last");+ assert.true(result.indexOf("b") < result.indexOf("d"));+ assert.true(result.indexOf("c") < result.indexOf("d"));+ });++ test("two independent before/after pairs stay separate", function (assert) {+ // Two unrelated pairs: (beforeA, a) and (b, afterB).+ // Each pair should be immediately adjacent, and the pairs+ // should not interleave.+ //+ // Expected: beforeA, a, b, afterB+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2);+ dag.add("beforeA", 3, { before: "a" });+ dag.add("afterB", 4, { after: "b" });++ const result = resolveKeys(dag);+ const beforeAIdx = result.indexOf("beforeA");+ const aIdx = result.indexOf("a");+ const bIdx = result.indexOf("b");+ const afterBIdx = result.indexOf("afterB");++ assert.true(beforeAIdx < aIdx, "beforeA is before a");+ assert.true(bIdx < afterBIdx, "b is before afterB");+ assert.strictEqual(aIdx - beforeAIdx, 1, "beforeA is immediately before a");+ assert.strictEqual(afterBIdx - bIdx, 1, "afterB is immediately after b");+ });++ test("before array and after array constraints", function (assert) {+ // d says { before: [b, c], after: a }, so d must come after a+ // and before both b and c.+ //+ // Expected: a, d, b, c+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2);+ dag.add("c", 3);+ dag.add("d", 4, { before: ["b", "c"], after: "a" });++ const result = resolveKeys(dag);+ assert.true(result.indexOf("a") < result.indexOf("d"), "d is after a");+ assert.true(result.indexOf("d") < result.indexOf("b"), "d is before b");+ assert.true(result.indexOf("d") < result.indexOf("c"), "d is before c");+ });++ /* Complex sequences */++ test("long chain with plugins inserting at different points", function (assert) {+ // Core defines a 5-item chain: a -> b -> c -> d -> e.+ // Three plugins each attach to a different point in the chain.+ // The core chain stays together because within each anchor group+ // the earlier-registered chain link outranks the plugin item.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });+ dag.add("c", 3, { after: "b" });+ dag.add("d", 4, { after: "c" });+ dag.add("e", 5, { after: "d" });+ dag.add("p1", 6, { after: "a" });+ dag.add("p2", 7, { after: "b" });+ dag.add("p3", 8, { after: "d" });++ const result = resolveKeys(dag);++ assert.deepEqual(+ result.slice(0, 5),+ ["a", "b", "c", "d", "e"],+ "core chain stays contiguous"+ );+ });++ test("multiple plugins with before constraints on the same target", function (assert) {+ // Core: header -> content -> footer. Four plugins say { before: "footer" }.+ // All four group right before footer, sidebar at the end.+ const dag = new DAG();+ dag.add("header", 1);+ dag.add("content", 2, { after: "header" });+ dag.add("footer", 3, { after: "content" });+ dag.add("plugin-a", 4, { before: "footer" });+ dag.add("sidebar", 5);+ dag.add("plugin-b", 6, { before: "footer" });+ dag.add("plugin-c", 7, { before: "footer" });+ dag.add("plugin-d", 8, { before: "footer" });++ const result = resolveKeys(dag);+ const footerIdx = result.indexOf("footer");++ for (const plugin of ["plugin-a", "plugin-b", "plugin-c", "plugin-d"]) {+ assert.true(+ result.indexOf(plugin) < footerIdx,+ `${plugin} before footer`+ );+ }+ assert.true(result.indexOf("sidebar") > footerIdx, "sidebar after footer");+ });++ test("two merging chains with shared sink", function (assert) {+ // a1 -> a2 -> a3 -\+ // -> merge -> final+ // b1 -> b2 -------/+ const dag = new DAG();+ dag.add("a1", 1);+ dag.add("a2", 2, { after: "a1" });+ dag.add("a3", 3, { after: "a2" });+ dag.add("b1", 4);+ dag.add("b2", 5, { after: "b1" });+ dag.add("merge", 6, { after: ["a3", "b2"] });+ dag.add("final", 7, { after: "merge" });++ const result = resolveKeys(dag);++ assert.deepEqual(+ [result.indexOf("a1"), result.indexOf("a2"), result.indexOf("a3")],+ [0, 1, 2],+ "a-chain is contiguous at the start"+ );+ assert.deepEqual(+ [result.indexOf("b1"), result.indexOf("b2")],+ [3, 4],+ "b-chain is contiguous after a-chain"+ );+ assert.strictEqual(result.indexOf("merge"), 5);+ assert.strictEqual(result.indexOf("final"), 6);+ });++ test("before chain: predecessors form their own chain before a target", function (assert) {+ // p1 -> p2 -> p3 -> target, all constrained. Unrelated at end.+ //+ // Expected: p1, p2, p3, target, unrelated+ const dag = new DAG();+ dag.add("target", 1);+ dag.add("p1", 2, { before: "target" });+ dag.add("p2", 3, { before: "target", after: "p1" });+ dag.add("p3", 4, { before: "target", after: "p2" });+ dag.add("unrelated", 5);++ assert.deepEqual(resolveKeys(dag), [+ "p1",+ "p2",+ "p3",+ "target",+ "unrelated",+ ]);+ });++ test("wide fan-out: one root with many independent successors", function (assert) {+ // root has 8 successors. They all group after root, with+ // unrelated items at the end.+ const dag = new DAG();+ dag.add("root", 0);+ dag.add("unrelated-1", 1);+ dag.add("s1", 2, { after: "root" });+ dag.add("s2", 3, { after: "root" });+ dag.add("unrelated-2", 4);+ dag.add("s3", 5, { after: "root" });+ dag.add("s4", 6, { after: "root" });+ dag.add("s5", 7, { after: "root" });+ dag.add("s6", 8, { after: "root" });+ dag.add("s7", 9, { after: "root" });+ dag.add("s8", 10, { after: "root" });++ const result = resolveKeys(dag);++ assert.strictEqual(result[0], "root");+ assert.deepEqual(+ result.slice(1, 9),+ ["s1", "s2", "s3", "s4", "s5", "s6", "s7", "s8"],+ "all successors grouped after root"+ );+ assert.deepEqual(+ result.slice(9),+ ["unrelated-1", "unrelated-2"],+ "unrelated items after the fan-out group"+ );+ });++ test("wide fan-in: many independent predecessors converge on one target", function (assert) {+ // 6 predecessors before target, with unrelated items interspersed.+ // All predecessors group contiguously before target.+ const dag = new DAG();+ dag.add("target", 0);+ dag.add("p1", 1, { before: "target" });+ dag.add("p2", 2, { before: "target" });+ dag.add("unrelated-1", 3);+ dag.add("p3", 4, { before: "target" });+ dag.add("p4", 5, { before: "target" });+ dag.add("unrelated-2", 6);+ dag.add("p5", 7, { before: "target" });+ dag.add("p6", 8, { before: "target" });++ const result = resolveKeys(dag);+ const targetIdx = result.indexOf("target");++ assert.deepEqual(+ result.slice(0, 6),+ ["p1", "p2", "p3", "p4", "p5", "p6"],+ "all predecessors are contiguous"+ );+ assert.true(+ result.indexOf("unrelated-1") > targetIdx,+ "unrelated-1 after target"+ );+ assert.true(+ result.indexOf("unrelated-2") > targetIdx,+ "unrelated-2 after target"+ );+ });++ test("complex toolbar: mixed before/after with sub-groups", function (assert) {+ // Core: bold -> italic -> underline -> separator-1 -> link ->+ // image -> separator-2 -> undo -> redo+ // Plugins pin between core items using both constraints.+ const dag = new DAG();+ dag.add("bold", 1);+ dag.add("italic", 2, { after: "bold" });+ dag.add("underline", 3, { after: "italic" });+ dag.add("separator-1", 4, { after: "underline" });+ dag.add("link", 5, { after: "separator-1" });+ dag.add("image", 6, { after: "link" });+ dag.add("separator-2", 7, { after: "image" });+ dag.add("undo", 8, { after: "separator-2" });+ dag.add("redo", 9, { after: "undo" });+ dag.add("strikethrough", 10, { before: "separator-1", after: "underline" });+ dag.add("emoji", 11, { before: "separator-2", after: "image" });+ dag.add("code", 12, { before: "link", after: "separator-1" });++ const result = resolveKeys(dag);++ const coreItems = [+ "bold",+ "italic",+ "underline",+ "separator-1",+ "link",+ "image",+ "separator-2",+ "undo",+ "redo",+ ];+ for (let i = 1; i < coreItems.length; i++) {+ assert.true(+ result.indexOf(coreItems[i - 1]) < result.indexOf(coreItems[i]),+ `${coreItems[i - 1]} before ${coreItems[i]}`+ );+ }++ assert.true(+ result.indexOf("strikethrough") > result.indexOf("underline"),+ "strikethrough after underline"+ );+ assert.true(+ result.indexOf("strikethrough") < result.indexOf("separator-1"),+ "strikethrough before separator-1"+ );+ assert.true(+ result.indexOf("code") > result.indexOf("separator-1"),+ "code after separator-1"+ );+ assert.true(+ result.indexOf("code") < result.indexOf("link"),+ "code before link"+ );+ assert.true(+ result.indexOf("emoji") > result.indexOf("image"),+ "emoji after image"+ );+ assert.true(+ result.indexOf("emoji") < result.indexOf("separator-2"),+ "emoji before separator-2"+ );+ });++ /* Real-world patterns */++ test("header icons pattern: items before search", function (assert) {+ // lang-switcher and color-selector before search, after-chain follows.+ const dag = new DAG();+ dag.add("search", 1);+ dag.add("hamburger", 2, { after: "search" });+ dag.add("user-menu", 3, { after: "hamburger" });+ dag.add("lang-switcher", 4, { before: "search" });+ dag.add("color-selector", 5, { before: "search", after: "lang-switcher" });++ const result = resolveKeys(dag);+ const searchIdx = result.indexOf("search");++ assert.true(result.indexOf("lang-switcher") < searchIdx);+ assert.true(result.indexOf("color-selector") < searchIdx);+ assert.true(+ result.indexOf("color-selector") > result.indexOf("lang-switcher")+ );+ assert.true(result.indexOf("hamburger") > searchIdx);+ });++ test("post menu pattern: items before show-more", function (assert) {+ // Core buttons without constraints, then items before show-more.+ const dag = new DAG();+ dag.add("like", 1);+ dag.add("share", 2);+ dag.add("flag", 3);+ dag.add("show-more", 4);+ dag.add("bookmark", 5, { before: "show-more" });+ dag.add("reply", 6, { before: "show-more" });+ dag.add("plugin-btn", 7, { before: "show-more" });++ const result = resolveKeys(dag);+ const showMoreIdx = result.indexOf("show-more");++ assert.true(result.indexOf("bookmark") < showMoreIdx);+ assert.true(result.indexOf("reply") < showMoreIdx);+ assert.true(result.indexOf("plugin-btn") < showMoreIdx);+ });++ /* Hub graphs: a defaultPosition pointing at one key gives that key a+ very high in-degree. Locality must survive that shape. */++ test("hub fan-in: before/after pair stays adjacent under a hub", function (assert) {+ // a, b, and unrelated all point at the hub. attached anchors after a,+ // so it must sit right between a and b; unrelated must not drift in.+ const dag = new DAG();+ dag.add("a", 1, { before: "hub" });+ dag.add("b", 2, { before: "hub" });+ dag.add("hub", 3);+ dag.add("unrelated", 4, { before: "hub" });+ dag.add("attached", 5, { after: "a", before: "b" });++ assert.deepEqual(resolveKeys(dag), [+ "a",+ "attached",+ "b",+ "unrelated",+ "hub",+ ]);+ });++ test("hub fan-in: item registered last with before-first leads the group", function (assert) {+ // prepended anchors before the group's first item, so registration+ // order must not sink it into the middle of the hub's predecessors.+ const dag = new DAG();+ dag.add("first", 1, { before: "hub" });+ dag.add("second", 2, { before: "hub" });+ dag.add("third", 3, { before: "hub" });+ dag.add("hub", 4);+ dag.add("prepended", 5, { before: "first" });++ assert.deepEqual(resolveKeys(dag), [+ "prepended",+ "first",+ "second",+ "third",+ "hub",+ ]);+ });++ test("hub via defaultPosition: anchored items keep their anchors adjacent", function (assert) {+ // Mirrors the post menu: every core button gets { before: "showMore" },+ // so showMore is a hub. Items added later with explicit anchors must+ // land next to those anchors, not where registration order puts them.+ const dag = new DAG({+ defaultPosition: { before: "showMore" },+ throwErrorOnCycle: false,+ });+ dag.add("read", 1, { before: ["showMore"] });+ dag.add("like", 2, { before: ["showMore"] });+ dag.add("copyLink", 3, { before: ["showMore"] });+ dag.add("showMore", 4, {});+ dag.add("reply", 5, { after: ["showMore"] });+ dag.add("plugin-first", 6, { before: "read" });+ dag.add("plugin-last", 7);+ dag.add("plugin-mid", 8, { after: "like", before: "copyLink" });+ dag.add("plugin-orphan", 9, { after: "absent-key" });++ assert.deepEqual(resolveKeys(dag), [+ "plugin-first",+ "read",+ "like",+ "plugin-mid",+ "copyLink",+ "plugin-last",+ "showMore",+ "reply",+ "plugin-orphan",+ ]);+ });++ test("absent after-anchor: item sorts at the end", function (assert) {+ // "missing" is referenced but never added, so it renders nothing and+ // sorts past every real item; the item anchored after it follows it+ // there instead of staying where it was registered, which would give+ // a, ghost-follower, b+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("ghost-follower", 2, { after: "missing" });+ dag.add("b", 3);++ assert.deepEqual(resolveKeys(dag), ["a", "b", "ghost-follower"]);+ });++ test("hub: a lone after-anchor lands adjacent, not past the hub", function (assert) {+ // A single anchor has to be enough on its own. The anchor's edge into+ // the hub must not drag its follower along: reaching "attached" only+ // through the hub would sort it last, giving+ // first, second, third, hub, trailing, attached+ const dag = new DAG(hubOptions());+ addHubGroup(dag);+ dag.add("attached", 6, { after: "first" });++ assert.deepEqual(resolveKeys(dag), [+ "first",+ "attached",+ "second",+ "third",+ "hub",+ "trailing",+ ]);+ });++ test("hub: anchoring after the last item before the hub", function (assert) {+ // "third" is the last item before the hub, so its follower belongs in+ // the gap between the two rather than beyond the hub's own successors,+ // which would give first, second, third, hub, trailing, attached+ const dag = new DAG(hubOptions());+ addHubGroup(dag);+ dag.add("attached", 6, { after: "third" });++ assert.deepEqual(resolveKeys(dag), [+ "first",+ "second",+ "third",+ "attached",+ "hub",+ "trailing",+ ]);+ });++ /* Single-anchor sufficiency: one anchor fully determines placement, so a+ second opposing anchor is redundant rather than load-bearing. */++ test("one anchor places an item identically to an anchor pair", function (assert) {+ // Callers should not have to name an opposing anchor to pin an item+ // down. Both forms resolve to+ // first, attached, second, third, hub, trailing+ // where a sort that honours only the pair would leave the single form+ // at first, second, third, hub, trailing, attached+ const single = new DAG(hubOptions());+ addHubGroup(single);+ single.add("attached", 6, { after: "first" });++ const pair = new DAG(hubOptions());+ addHubGroup(pair);+ pair.add("attached", 6, { after: "first", before: "second" });++ assert.deepEqual(+ resolveKeys(single),+ resolveKeys(pair),+ "the redundant before-anchor does not change the result"+ );+ });++ test("sequential surface: a lone after-anchor does not displace its anchor", function (assert) {+ // Surfaces without a defaultPosition add their items unconstrained.+ // Giving "gamma" a follower must not move "gamma" itself: pushing the+ // pair to the end would reorder the untouched items too, giving+ // alpha, beta, delta, epsilon, gamma, inserted+ const dag = new DAG();+ for (const key of ["alpha", "beta", "gamma", "delta", "epsilon"]) {+ dag.add(key, key);+ }+ dag.add("inserted", 9, { after: "gamma" });++ assert.deepEqual(resolveKeys(dag), [+ "alpha",+ "beta",+ "gamma",+ "inserted",+ "delta",+ "epsilon",+ ]);+ });++ test("chain of after-links stays contiguous", function (assert) {+ // Each link anchors to the previous one, so the whole chain trails the+ // item it was appended to.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2);+ dag.add("c", 3);+ dag.add("x1", 4, { after: "c" });+ dag.add("x2", 5, { after: "x1" });+ dag.add("x3", 6, { after: "x2" });++ assert.deepEqual(resolveKeys(dag), ["a", "b", "c", "x1", "x2", "x3"]);+ });++ test("contested anchor: followers group in registration order", function (assert) {+ // Two items claim the slot after the same anchor. Both join the+ // anchor's group, earlier registration first, rather than the later+ // one being left at its registration point:+ // anchor, early-follower, tail, late-follower+ const dag = new DAG();+ dag.add("anchor", 1);+ dag.add("early-follower", 2, { after: "anchor" });+ dag.add("tail", 3);+ dag.add("late-follower", 4, { after: "anchor" });++ assert.deepEqual(resolveKeys(dag), [+ "anchor",+ "early-follower",+ "late-follower",+ "tail",+ ]);+ });++ /* Before-side mirrors of the guarantees above. The two sides are ranked+ by separate branches, so each needs its own coverage. */++ test("hub: a lone before-anchor lands adjacent", function (assert) {+ const dag = new DAG(hubOptions());+ addHubGroup(dag);+ dag.add("attached", 6, { before: "third" });++ assert.deepEqual(resolveKeys(dag), [+ "first",+ "second",+ "attached",+ "third",+ "hub",+ "trailing",+ ]);+ });++ test("sequential surface: a lone before-anchor does not displace its anchor", function (assert) {+ const dag = new DAG();+ for (const key of ["alpha", "beta", "gamma", "delta", "epsilon"]) {+ dag.add(key, key);+ }+ dag.add("inserted", 9, { before: "gamma" });++ assert.deepEqual(resolveKeys(dag), [+ "alpha",+ "beta",+ "inserted",+ "gamma",+ "delta",+ "epsilon",+ ]);+ });++ test("chain of before-links stays contiguous", function (assert) {+ // Each link anchors before the previous one, so the chain builds+ // backwards and lands ahead of the item it was anchored to.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2);+ dag.add("c", 3);+ dag.add("x1", 4, { before: "a" });+ dag.add("x2", 5, { before: "x1" });+ dag.add("x3", 6, { before: "x2" });++ assert.deepEqual(resolveKeys(dag), ["x3", "x2", "x1", "a", "b", "c"]);+ });++ test("a lone before array anchors to the nearest listed key", function (assert) {+ // Listing several keys means "ahead of all of them"; the item settles+ // against the closest one rather than the furthest.+ const dag = new DAG();+ dag.add("p", 1);+ dag.add("q", 2);+ dag.add("r", 3);+ dag.add("multi", 4, { before: ["q", "r"] });++ assert.deepEqual(resolveKeys(dag), ["p", "multi", "q", "r"]);+ });++ test("absent before-anchor is ignored", function (assert) {+ // Mirrors "absent after-anchor" and is deliberately asymmetric: an+ // absent key sorts past every real item, so a before-constraint on it+ // is vacuous and the item keeps its own position, while an+ // after-constraint on it would carry the item to the end.+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("ghost", 2, { before: "missing" });+ dag.add("b", 3);++ assert.deepEqual(resolveKeys(dag), ["a", "ghost", "b"]);+ });++ test("before and after together: the after anchor decides placement", function (assert) {+ // Both anchors are honoured as ordering edges, but they disagree about+ // where the item belongs. It hugs what it follows, so it sits against+ // "w" rather than drifting down to "z".+ const dag = new DAG();+ dag.add("w", 1);+ dag.add("x", 2);+ dag.add("y", 3);+ dag.add("z", 4);+ dag.add("mid", 5, { after: "w", before: "z" });++ assert.deepEqual(resolveKeys(dag), ["w", "mid", "x", "y", "z"]);+ });++ /* replace/reposition cycle handling */++ test("replace with cycle-creating position throws and leaves DAG unchanged", function (assert) {+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });+ dag.add("c", 3, { after: "b" });++ assert.throws(+ () => dag.replace("a", "new-value", { after: "c" }),+ /cycle detected/+ );++ assert.deepEqual(+ resolveKeys(dag),+ ["a", "b", "c"],+ "DAG order unchanged after failed replace"+ );+ assert.deepEqual(+ dag.resolve().map((e) => e.value),+ [1, 2, 3],+ "values unchanged after failed replace"+ );+ });++ test("reposition with cycle-creating position throws and leaves DAG unchanged", function (assert) {+ const dag = new DAG();+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });+ dag.add("c", 3, { after: "b" });++ assert.throws(() => dag.reposition("a", { after: "c" }), /cycle detected/);++ assert.deepEqual(+ resolveKeys(dag),+ ["a", "b", "c"],+ "DAG order unchanged after failed reposition"+ );+ });++ test("replace with cycle and throwErrorOnCycle false falls back gracefully", function (assert) {+ const dag = new DAG({+ throwErrorOnCycle: false,+ defaultPosition: { before: "c" },+ });+ dag.add("a", 1);+ dag.add("b", 2, { after: "a" });+ dag.add("c", 3, { after: "b" });++ dag.replace("a", "new-value", { after: "c" });++ assert.true(dag.has("a"), "a still exists");+ const result = dag.resolve();+ assert.strictEqual(+ result.find((e) => e.key === "a").value,+ "new-value",+ "value was updated"+ );+ });+});diff --git a/frontend/discourse/type-tests/lib/dag-test.ts b/frontend/discourse/type-tests/lib/dag-test.tsnew file mode 100644index 00000000000..0b0499c3e14--- /dev/null+++ b/frontend/discourse/type-tests/lib/dag-test.ts@@ -0,0 +1,34 @@+import { expectTypeOf } from "expect-type";+import DAG, {+ type DAGOptions,+ type DAGPosition,+ type DAGResolvedEntry,+} from "discourse/lib/dag";++// The value type threads through resolve(), entries(), and add().+const stringDag = new DAG<string>();+expectTypeOf(stringDag.resolve()).toEqualTypeOf<DAGResolvedEntry<string>[]>();+expectTypeOf(stringDag.resolve()[0].value).toEqualTypeOf<string>();+expectTypeOf(stringDag.entries()).toEqualTypeOf<+ Array<[string, string, DAGPosition]>+>();+expectTypeOf(stringDag.add).parameter(1).toEqualTypeOf<string>();++// from() infers the value type from its entries.+const numberDag = DAG.from([["a", 1]] as Array<[string, number, DAGPosition?]>);+expectTypeOf(numberDag).toEqualTypeOf<DAG<number>>();+expectTypeOf(numberDag.resolve()[0].value).toEqualTypeOf<number>();++// Omitting the type argument defaults the value to `unknown`.+expectTypeOf(new DAG().resolve()[0].value).toEqualTypeOf<unknown>();++// Lifecycle callbacks receive the value type.+expectTypeOf<DAGOptions<string>["onAddItem"]>()+ .parameter(1)+ .toEqualTypeOf<string>();+expectTypeOf<DAGOptions<string>["onReplaceItem"]>()+ .parameter(1)+ .toEqualTypeOf<string>();+expectTypeOf<DAGOptions<string>["onReplaceItem"]>()+ .parameter(2)+ .toEqualTypeOf<string>();