@xsynaptic/path-suggestions 0.1.0

package/LICENSE

@@ -0,0 +1,48 @@
+MIT License
+
+Copyright (c) 2026 Alexander Synaptic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This software is derived in part from alfaaz (https://github.com/thecodrr/alfaaz),
+which is distributed under the MIT License:
+
+MIT License
+
+Copyright (c) 2023 Abdullah Atta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @xsynaptic/path-suggestions
+
+A helper utility for 404 pages. Scores the path a visitor asked for against the paths that actually exist, then lists the closest matches, or redirects outright when one scores high enough. It ships as two independent pieces: a scoring function with no DOM dependency, and a custom element that drives a 404 page. Either works without the other.
+
+_Note_: this package is ESM-only.
+
+## Install
+
+```sh
+npm install @xsynaptic/path-suggestions
+```
+
+## Use the element
+
+Publish a JSON file listing the paths worth suggesting, as an array of `{ url, title }`, then point the element at it:
+
+```html
+<path-suggestions src="/content-manifest.json" link-class="anchor">
+	<p>Did you mean one of these?</p>
+</path-suggestions>
+
+<script type="module">
+	import '@xsynaptic/path-suggestions/element';
+</script>
+```
+
+The element appends its own `<ul>` and leaves any other children in place, so the heading above survives. Everything renders in the light DOM, so ordinary stylesheet rules apply to the list.
+
+Set `.entries` to score against an inlined list and skip the fetch. A value set before the element upgrades survives the upgrade, and a value set afterwards scores again, so it does not matter which script runs first:
+
+```js
+document.querySelector('path-suggestions').entries = [{ url: '/about/', title: 'About' }];
+```
+
+### Attributes
+
+| Attribute            | Default | Meaning                                                        |
+| -------------------- | ------- | -------------------------------------------------------------- |
+| `src`                |         | URL of the JSON manifest; omit when setting `.entries`         |
+| `threshold`          | `0.5`   | Score below which a candidate is discarded                     |
+| `redirect-threshold` | `0.92`  | Score at or above which the best candidate triggers a redirect |
+| `limit`              | `5`     | Most suggestions to render                                     |
+| `min-length`         | `3`     | Paths shorter than this carry too little signal to score       |
+| `link-class`         |         | Class applied to each anchor                                   |
+
+### State and events
+
+The element sets `data-state` to `loading`, then to `list`, `empty`, or `redirect`, which is enough to drive a loading indicator or hide a heading:
+
+```css
+path-suggestions:not([data-state='list']) p {
+	display: none;
+}
+```
+
+Both events bubble. `path-suggestions:redirect` fires with `detail.url` before the element navigates, and is cancelable; cancel it to navigate through a client-side router instead. `path-suggestions:done` fires once the element has settled, with `detail.count`.
+
+```js
+document.addEventListener('path-suggestions:redirect', (event) => {
+	event.preventDefault();
+	router.replace(event.detail.url);
+});
+```
+
+## Use the scoring function
+
+The scoring function has no DOM dependency, so it also runs in a build script or a link checker:
+
+```ts
+import { getPathSuggestions } from '@xsynaptic/path-suggestions';
+
+getPathSuggestions({ path: '/example', entries });
+// { type: 'redirect', url: '/example-post/' }
+```
+
+Returns `undefined` when nothing clears the threshold, `{ type: 'redirect', url }` when the best candidate clears `redirectThreshold`, and `{ type: 'list', items }` otherwise, where each item carries its `score`.
+
+Trailing slashes are stripped before comparing, so a candidate matching the requested path never triggers a redirect, and neither does one differing only by a trailing slash. That last case is canonicalization, and belongs in a 301 at the host.
+
+`getPathSimilarity(a, b)` is the underlying score, from 0 to 1. It takes any two strings, so it has uses beyond 404 pages: naming the nearest valid ID when a content reference fails to resolve, for one.
+
+## How the score works
+
+Edit distance, via [fastest-levenshtein][], measured against the longer of the two strings, so `1` is identical. A bonus applies when either string contains the other, which lifts a truncated path above candidates that merely run to a similar length. Truncation is the common failure: a half-typed slug, or a link that lost its tail. That bonus is clamped, so a path that is a strict prefix of a real one scores exactly `1`.
+
+## License
+
+[MIT][mit-license]
+
+[fastest-levenshtein]: https://github.com/ka-weihe/fastest-levenshtein
+[mit-license]: https://opensource.org/licenses/MIT

package/dist/element.d.mts

@@ -0,0 +1,33 @@
+import { PathEntry } from "./index.mjs";
+//#region src/element.d.ts
+declare const pathSuggestionsElementName = "path-suggestions";
+declare const pathSuggestionsRedirectEvent = "path-suggestions:redirect";
+declare const pathSuggestionsDoneEvent = "path-suggestions:done";
+interface PathSuggestionsDoneDetail {
+  count: number;
+}
+interface PathSuggestionsRedirectDetail {
+  url: string;
+}
+declare class PathSuggestionsElement extends HTMLElement {
+  #private;
+  get entries(): Array<PathEntry> | undefined;
+  set entries(value: Array<PathEntry> | undefined);
+  constructor();
+  connectedCallback(): void;
+  run(): Promise<void>;
+  private fetchEntries;
+  private finish;
+  private getList;
+  private readNumber;
+  private redirect;
+  private render;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'path-suggestions': PathSuggestionsElement;
+  }
+}
+//#endregion
+export { PathSuggestionsDoneDetail, PathSuggestionsElement, PathSuggestionsRedirectDetail, pathSuggestionsDoneEvent, pathSuggestionsElementName, pathSuggestionsRedirectEvent };
+//# sourceMappingURL=element.d.mts.map

package/dist/element.mjs

@@ -0,0 +1,119 @@
+import { getPathSuggestions, pathSuggestionDefaults } from "./index.mjs";
+//#region src/element.ts
+const pathSuggestionsElementName = "path-suggestions";
+const pathSuggestionsRedirectEvent = "path-suggestions:redirect";
+const pathSuggestionsDoneEvent = "path-suggestions:done";
+const defaultMinLength = 3;
+const listAttribute = "data-path-suggestions-list";
+var PathSuggestionsElement = class extends HTMLElement {
+	get entries() {
+		return this.#entries;
+	}
+	set entries(value) {
+		this.#entries = value;
+		if (this.isConnected) this.run();
+	}
+	#entries;
+	constructor() {
+		super();
+		if (Object.hasOwn(this, "entries")) {
+			this.#entries = this.entries;
+			Reflect.deleteProperty(this, "entries");
+		}
+	}
+	connectedCallback() {
+		this.run();
+	}
+	async run() {
+		this.dataset.state = "loading";
+		const path = globalThis.location.pathname;
+		if (path.length < this.readNumber("min-length", defaultMinLength)) {
+			this.finish(0, "empty");
+			return;
+		}
+		const entries = this.entries ?? await this.fetchEntries();
+		if (!entries) {
+			this.finish(0, "empty");
+			return;
+		}
+		const result = getPathSuggestions({
+			entries,
+			limit: this.readNumber("limit", pathSuggestionDefaults.limit),
+			path,
+			redirectThreshold: this.readNumber("redirect-threshold", pathSuggestionDefaults.redirectThreshold),
+			threshold: this.readNumber("threshold", pathSuggestionDefaults.threshold)
+		});
+		if (!result) {
+			this.finish(0, "empty");
+			return;
+		}
+		if (result.type === "redirect") {
+			this.redirect(result.url);
+			return;
+		}
+		this.render(result.items);
+		this.finish(result.items.length, "list");
+	}
+	async fetchEntries() {
+		const source = this.getAttribute("src");
+		if (!source) return;
+		try {
+			const response = await fetch(source);
+			if (!response.ok) return;
+			const entries = await response.json();
+			return Array.isArray(entries) ? entries : void 0;
+		} catch {
+			return;
+		}
+	}
+	finish(count, state) {
+		this.dataset.state = state;
+		this.dispatchEvent(new CustomEvent(pathSuggestionsDoneEvent, {
+			bubbles: true,
+			detail: { count }
+		}));
+	}
+	getList() {
+		const existing = this.querySelector(`ul[${CSS.escape(listAttribute)}]`);
+		if (existing) return existing;
+		const list = document.createElement("ul");
+		list.setAttribute(listAttribute, "");
+		this.append(list);
+		return list;
+	}
+	readNumber(attribute, fallback) {
+		const raw = this.getAttribute(attribute);
+		if (raw === null) return fallback;
+		const parsed = Number(raw);
+		return Number.isFinite(parsed) ? parsed : fallback;
+	}
+	redirect(url) {
+		const event = new CustomEvent(pathSuggestionsRedirectEvent, {
+			bubbles: true,
+			cancelable: true,
+			detail: { url }
+		});
+		const isProceed = this.dispatchEvent(event);
+		this.finish(1, "redirect");
+		if (isProceed) globalThis.location.replace(url);
+	}
+	render(items) {
+		const list = this.getList();
+		const linkClass = this.getAttribute("link-class");
+		list.replaceChildren();
+		for (const item of items) {
+			const listItem = document.createElement("li");
+			const link = document.createElement("a");
+			link.href = item.url;
+			link.textContent = item.title;
+			if (linkClass) link.className = linkClass;
+			listItem.append(link);
+			list.append(listItem);
+		}
+	}
+};
+if (!customElements.get("path-suggestions")) customElements.define(pathSuggestionsElementName, PathSuggestionsElement);
+//#endregion
+export { PathSuggestionsElement, pathSuggestionsDoneEvent, pathSuggestionsElementName, pathSuggestionsRedirectEvent };
+
+//# sourceMappingURL=element.mjs.map

package/dist/element.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.mjs","names":["#entries"],"sources":["../src/element.ts"],"sourcesContent":["import type { PathEntry, PathSuggestion } from './index.js';\n\nimport { getPathSuggestions, pathSuggestionDefaults } from './index.js';\n\nexport const pathSuggestionsElementName = 'path-suggestions';\n\nexport const pathSuggestionsRedirectEvent = 'path-suggestions:redirect';\nexport const pathSuggestionsDoneEvent = 'path-suggestions:done';\n\nexport interface PathSuggestionsDoneDetail {\n\tcount: number;\n}\n\nexport interface PathSuggestionsRedirectDetail {\n\turl: string;\n}\n\ntype PathSuggestionsState = 'empty' | 'list' | 'redirect';\n\n// A path this short carries too little signal to score against anything\nconst defaultMinLength = 3;\n\n// Marks the list this element owns, so host-authored children survive a re-render\nconst listAttribute = 'data-path-suggestions-list';\n\nexport class PathSuggestionsElement extends HTMLElement {\n\t// Score against an inlined list instead of fetching one; scoring reruns when set after connection\n\tget entries(): Array<PathEntry> | undefined {\n\t\treturn this.#entries;\n\t}\n\n\tset entries(value: Array<PathEntry> | undefined) {\n\t\tthis.#entries = value;\n\n\t\tif (this.isConnected) void this.run();\n\t}\n\n\t#entries: Array<PathEntry> | undefined;\n\n\tconstructor() {\n\t\tsuper();\n\n\t\t// A value assigned before this element upgraded sits in an own property, shadowing the accessor\n\t\tif (Object.hasOwn(this, 'entries')) {\n\t\t\tthis.#entries = this.entries;\n\t\t\tReflect.deleteProperty(this, 'entries');\n\t\t}\n\t}\n\n\tconnectedCallback(): void {\n\t\tvoid this.run();\n\t}\n\n\tasync run(): Promise<void> {\n\t\tthis.dataset.state = 'loading';\n\n\t\tconst path = globalThis.location.pathname;\n\n\t\tif (path.length < this.readNumber('min-length', defaultMinLength)) {\n\t\t\tthis.finish(0, 'empty');\n\t\t\treturn;\n\t\t}\n\n\t\tconst entries = this.entries ?? (await this.fetchEntries());\n\n\t\tif (!entries) {\n\t\t\tthis.finish(0, 'empty');\n\t\t\treturn;\n\t\t}\n\n\t\tconst result = getPathSuggestions({\n\t\t\tentries,\n\t\t\tlimit: this.readNumber('limit', pathSuggestionDefaults.limit),\n\t\t\tpath,\n\t\t\tredirectThreshold: this.readNumber(\n\t\t\t\t'redirect-threshold',\n\t\t\t\tpathSuggestionDefaults.redirectThreshold,\n\t\t\t),\n\t\t\tthreshold: this.readNumber('threshold', pathSuggestionDefaults.threshold),\n\t\t});\n\n\t\tif (!result) {\n\t\t\tthis.finish(0, 'empty');\n\t\t\treturn;\n\t\t}\n\n\t\tif (result.type === 'redirect') {\n\t\t\tthis.redirect(result.url);\n\t\t\treturn;\n\t\t}\n\n\t\tthis.render(result.items);\n\t\tthis.finish(result.items.length, 'list');\n\t}\n\n\tprivate async fetchEntries(): Promise<Array<PathEntry> | undefined> {\n\t\tconst source = this.getAttribute('src');\n\n\t\tif (!source) return;\n\n\t\ttry {\n\t\t\tconst response = await fetch(source);\n\n\t\t\tif (!response.ok) return;\n\n\t\t\tconst entries: unknown = await response.json();\n\n\t\t\treturn Array.isArray(entries) ? (entries as Array<PathEntry>) : undefined;\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t}\n\n\tprivate finish(count: number, state: PathSuggestionsState): void {\n\t\tthis.dataset.state = state;\n\t\tthis.dispatchEvent(\n\t\t\tnew CustomEvent<PathSuggestionsDoneDetail>(pathSuggestionsDoneEvent, {\n\t\t\t\tbubbles: true,\n\t\t\t\tdetail: { count },\n\t\t\t}),\n\t\t);\n\t}\n\n\tprivate getList(): HTMLUListElement {\n\t\tconst existing = this.querySelector<HTMLUListElement>(`ul[${CSS.escape(listAttribute)}]`);\n\n\t\tif (existing) return existing;\n\n\t\tconst list = document.createElement('ul');\n\n\t\tlist.setAttribute(listAttribute, '');\n\t\tthis.append(list);\n\n\t\treturn list;\n\t}\n\n\tprivate readNumber(attribute: string, fallback: number): number {\n\t\tconst raw = this.getAttribute(attribute);\n\n\t\tif (raw === null) return fallback;\n\n\t\tconst parsed = Number(raw);\n\n\t\treturn Number.isFinite(parsed) ? parsed : fallback;\n\t}\n\n\t// Cancel the event to navigate some other way, such as an SPA router\n\tprivate redirect(url: string): void {\n\t\tconst event = new CustomEvent<PathSuggestionsRedirectDetail>(pathSuggestionsRedirectEvent, {\n\t\t\tbubbles: true,\n\t\t\tcancelable: true,\n\t\t\tdetail: { url },\n\t\t});\n\n\t\tconst isProceed = this.dispatchEvent(event);\n\n\t\tthis.finish(1, 'redirect');\n\n\t\tif (isProceed) globalThis.location.replace(url);\n\t}\n\n\tprivate render(items: Array<PathSuggestion>): void {\n\t\tconst list = this.getList();\n\t\tconst linkClass = this.getAttribute('link-class');\n\n\t\tlist.replaceChildren();\n\n\t\tfor (const item of items) {\n\t\t\tconst listItem = document.createElement('li');\n\t\t\tconst link = document.createElement('a');\n\n\t\t\tlink.href = item.url;\n\t\t\tlink.textContent = item.title;\n\n\t\t\tif (linkClass) link.className = linkClass;\n\n\t\t\tlistItem.append(link);\n\t\t\tlist.append(listItem);\n\t\t}\n\t}\n}\n\ndeclare global {\n\tinterface HTMLElementTagNameMap {\n\t\t'path-suggestions': PathSuggestionsElement;\n\t}\n}\n\nif (!customElements.get(pathSuggestionsElementName)) {\n\tcustomElements.define(pathSuggestionsElementName, PathSuggestionsElement);\n}\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,44 @@
+//#region src/index.d.ts
+interface PathEntry {
+  title: string;
+  url: string;
+}
+interface PathSuggestion extends PathEntry {
+  score: number;
+}
+interface PathSuggestionsOptions {
+  entries: Array<PathEntry>;
+  limit?: number;
+  path: string;
+  redirectThreshold?: number;
+  threshold?: number;
+}
+type PathSuggestionsResult = {
+  items: Array<PathSuggestion>;
+  type: 'list';
+} | {
+  type: 'redirect';
+  url: string;
+};
+declare const pathSuggestionDefaults: {
+  readonly limit: 5;
+  readonly redirectThreshold: 0.92;
+  readonly threshold: 0.5;
+};
+/**
+ * Score two strings from 0 (nothing in common) to 1 (identical)
+ *
+ * Edit distance relative to the longer string, plus a bonus when one contains the other
+ */
+declare function getPathSimilarity(a: string, b: string): number;
+/**
+ * Rank known paths against the one requested
+ *
+ * Returns `undefined` when nothing clears the threshold, a redirect when the best candidate clears
+ * `redirectThreshold` and is not the path already requested, and a list otherwise
+ */
+declare function getPathSuggestions(options: PathSuggestionsOptions): PathSuggestionsResult | undefined;
+declare function normalizePath(path: string): string;
+//#endregion
+export { PathEntry, PathSuggestion, PathSuggestionsOptions, PathSuggestionsResult, getPathSimilarity, getPathSuggestions, normalizePath, pathSuggestionDefaults };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,53 @@
+import { distance } from "fastest-levenshtein";
+//#region src/index.ts
+const pathSuggestionDefaults = {
+	limit: 5,
+	redirectThreshold: .92,
+	threshold: .5
+};
+const substringBonus = .3;
+/**
+* Score two strings from 0 (nothing in common) to 1 (identical)
+*
+* Edit distance relative to the longer string, plus a bonus when one contains the other
+*/
+function getPathSimilarity(a, b) {
+	const longest = Math.max(a.length, b.length);
+	if (longest === 0) return 1;
+	const base = 1 - distance(a, b) / longest;
+	const bonus = a.includes(b) || b.includes(a) ? substringBonus : 0;
+	return Math.min(1, base + bonus);
+}
+/**
+* Rank known paths against the one requested
+*
+* Returns `undefined` when nothing clears the threshold, a redirect when the best candidate clears
+* `redirectThreshold` and is not the path already requested, and a list otherwise
+*/
+function getPathSuggestions(options) {
+	const limit = options.limit ?? pathSuggestionDefaults.limit;
+	const redirectThreshold = options.redirectThreshold ?? pathSuggestionDefaults.redirectThreshold;
+	const threshold = options.threshold ?? pathSuggestionDefaults.threshold;
+	const current = normalizePath(options.path);
+	const scored = options.entries.map((entry) => ({
+		...entry,
+		score: getPathSimilarity(current, normalizePath(entry.url))
+	})).sort((suggestionA, suggestionB) => suggestionB.score - suggestionA.score);
+	const best = scored.at(0);
+	if (!best || best.score < threshold) return;
+	if (best.score >= redirectThreshold && normalizePath(best.url) !== current) return {
+		type: "redirect",
+		url: best.url
+	};
+	return {
+		items: scored.filter((suggestion) => suggestion.score >= threshold).slice(0, limit),
+		type: "list"
+	};
+}
+function normalizePath(path) {
+	return path.replace(/\/+$/, "") || "/";
+}
+//#endregion
+export { getPathSimilarity, getPathSuggestions, normalizePath, pathSuggestionDefaults };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { distance } from 'fastest-levenshtein';\n\nexport interface PathEntry {\n\ttitle: string;\n\turl: string;\n}\n\nexport interface PathSuggestion extends PathEntry {\n\tscore: number;\n}\n\nexport interface PathSuggestionsOptions {\n\tentries: Array<PathEntry>;\n\tlimit?: number;\n\t// The path the visitor asked for, normally location.pathname\n\tpath: string;\n\t// Score at or above which the best candidate is redirected to instead of listed\n\tredirectThreshold?: number;\n\t// Score below which a candidate is discarded\n\tthreshold?: number;\n}\n\nexport type PathSuggestionsResult =\n\t{ items: Array<PathSuggestion>; type: 'list' } | { type: 'redirect'; url: string };\n\n// Shared with the custom element, which reads its own attribute fallbacks from here\nexport const pathSuggestionDefaults = {\n\tlimit: 5,\n\tredirectThreshold: 0.92,\n\tthreshold: 0.5,\n} as const;\n\n// Lifts a truncated path (\"/sanwan-yue\" for \"/sanwan-yuemei-suspension-bridge\") above length-similar candidates\nconst substringBonus = 0.3;\n\n/**\n * Score two strings from 0 (nothing in common) to 1 (identical)\n *\n * Edit distance relative to the longer string, plus a bonus when one contains the other\n */\nexport function getPathSimilarity(a: string, b: string): number {\n\tconst longest = Math.max(a.length, b.length);\n\n\tif (longest === 0) return 1;\n\n\tconst base = 1 - distance(a, b) / longest;\n\tconst bonus = a.includes(b) || b.includes(a) ? substringBonus : 0;\n\n\treturn Math.min(1, base + bonus);\n}\n\n/**\n * Rank known paths against the one requested\n *\n * Returns `undefined` when nothing clears the threshold, a redirect when the best candidate clears\n * `redirectThreshold` and is not the path already requested, and a list otherwise\n */\nexport function getPathSuggestions(\n\toptions: PathSuggestionsOptions,\n): PathSuggestionsResult | undefined {\n\tconst limit = options.limit ?? pathSuggestionDefaults.limit;\n\tconst redirectThreshold = options.redirectThreshold ?? pathSuggestionDefaults.redirectThreshold;\n\tconst threshold = options.threshold ?? pathSuggestionDefaults.threshold;\n\n\tconst current = normalizePath(options.path);\n\n\tconst scored = options.entries\n\t\t.map((entry) => ({ ...entry, score: getPathSimilarity(current, normalizePath(entry.url)) }))\n\t\t// eslint-disable-next-line unicorn/no-array-sort -- toSorted needs Firefox 115; map() above already returned a fresh array\n\t\t.sort((suggestionA, suggestionB) => suggestionB.score - suggestionA.score);\n\n\tconst best = scored.at(0);\n\n\tif (!best || best.score < threshold) return;\n\n\tif (best.score >= redirectThreshold && normalizePath(best.url) !== current) {\n\t\treturn { type: 'redirect', url: best.url };\n\t}\n\n\treturn {\n\t\titems: scored.filter((suggestion) => suggestion.score >= threshold).slice(0, limit),\n\t\ttype: 'list',\n\t};\n}\n\nexport function normalizePath(path: string): string {\n\treturn path.replace(/\\/+$/, '') || '/';\n}\n"],"mappings":";;AA0BA,MAAa,yBAAyB;CACrC,OAAO;CACP,mBAAmB;CACnB,WAAW;AACZ;AAGA,MAAM,iBAAiB;;;;;;AAOvB,SAAgB,kBAAkB,GAAW,GAAmB;CAC/D,MAAM,UAAU,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM;CAE3C,IAAI,YAAY,GAAG,OAAO;CAE1B,MAAM,OAAO,IAAI,SAAS,GAAG,CAAC,IAAI;CAClC,MAAM,QAAQ,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,iBAAiB;CAEhE,OAAO,KAAK,IAAI,GAAG,OAAO,KAAK;AAChC;;;;;;;AAQA,SAAgB,mBACf,SACoC;CACpC,MAAM,QAAQ,QAAQ,SAAS,uBAAuB;CACtD,MAAM,oBAAoB,QAAQ,qBAAqB,uBAAuB;CAC9E,MAAM,YAAY,QAAQ,aAAa,uBAAuB;CAE9D,MAAM,UAAU,cAAc,QAAQ,IAAI;CAE1C,MAAM,SAAS,QAAQ,QACrB,KAAK,WAAW;EAAE,GAAG;EAAO,OAAO,kBAAkB,SAAS,cAAc,MAAM,GAAG,CAAC;CAAE,EAAE,CAAC,CAE3F,MAAM,aAAa,gBAAgB,YAAY,QAAQ,YAAY,KAAK;CAE1E,MAAM,OAAO,OAAO,GAAG,CAAC;CAExB,IAAI,CAAC,QAAQ,KAAK,QAAQ,WAAW;CAErC,IAAI,KAAK,SAAS,qBAAqB,cAAc,KAAK,GAAG,MAAM,SAClE,OAAO;EAAE,MAAM;EAAY,KAAK,KAAK;CAAI;CAG1C,OAAO;EACN,OAAO,OAAO,QAAQ,eAAe,WAAW,SAAS,SAAS,CAAC,CAAC,MAAM,GAAG,KAAK;EAClF,MAAM;CACP;AACD;AAEA,SAAgB,cAAc,MAAsB;CACnD,OAAO,KAAK,QAAQ,QAAQ,EAAE,KAAK;AACpC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@xsynaptic/path-suggestions",
+  "version": "0.1.0",
+  "description": "A did-you-mean for 404 pages, as a DOM-free scoring function plus an optional custom element",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alexander Synaptic <x@synapticism.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xsynaptic/astro-lab.git",
+    "directory": "packages/path-suggestions"
+  },
+  "homepage": "https://github.com/xsynaptic/astro-lab/tree/main/packages/path-suggestions#readme",
+  "bugs": {
+    "url": "https://github.com/xsynaptic/astro-lab/issues"
+  },
+  "keywords": [
+    "404",
+    "custom-element",
+    "did-you-mean",
+    "levenshtein",
+    "not-found",
+    "suggestions"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./element": {
+      "types": "./dist/element.d.mts",
+      "import": "./dist/element.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "./dist/element.mjs"
+  ],
+  "dependencies": {
+    "fastest-levenshtein": "^1.0.16"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit"
+  }
+}