acrylblends 0.8.1 → 0.9.0

package/lib/kv/conformance.js

@@ -0,0 +1,301 @@
+import { afterEach, describe, expect, it } from "vitest";
+//#region ../../plugins/acryl-kv/src/conformance.ts
+/**
+* The `kv` conformance suite: what every provider of the port must do, as Vitest tests. A provider passes it to be accepted
+* (`describeKvConformance('acryl-kv-json', open)` in its own tests), so the same cases run on a file and on SQL.
+*/
+function describeKvConformance(provider, open) {
+	describe(`kv conformance: ${provider}`, () => {
+		const opened = [];
+		const track = (subject) => {
+			opened.push(subject);
+			return subject;
+		};
+		const fresh = async () => track(await open()).kv;
+		afterEach(async () => {
+			await Promise.all(opened.splice(0).map((subject) => subject.close()));
+		});
+		it("round-trips null, booleans, numbers, text with unicode, arrays and nested objects", async () => {
+			const kv = await fresh();
+			for (const [index, value] of [
+				null,
+				true,
+				false,
+				0,
+				-1.5,
+				9007199254740991,
+				"",
+				"café ✓ 😀",
+				[],
+				[1, [2, [3]]],
+				{},
+				{
+					a: { b: [1, { c: null }] },
+					"ключ": "значение"
+				}
+			].entries()) {
+				await kv.set(`value/${index}`, value);
+				expect(await kv.get(`value/${index}`), JSON.stringify(value)).toEqual(value);
+			}
+		});
+		it("answers get with undefined for a missing key, and overwrites on set", async () => {
+			const kv = await fresh();
+			expect(await kv.get("missing")).toBeUndefined();
+			await kv.set("k", { n: 1 });
+			await kv.set("k", { n: 2 });
+			expect(await kv.get("k")).toEqual({ n: 2 });
+		});
+		it("deletes a key, and a missing key is not an error", async () => {
+			const kv = await fresh();
+			await kv.set("k", 1);
+			await kv.delete("k");
+			expect(await kv.get("k")).toBeUndefined();
+			await expect(kv.delete("k")).resolves.toBeUndefined();
+			await expect(kv.delete("never-existed")).resolves.toBeUndefined();
+		});
+		it("stores a null value as null, apart from a missing key", async () => {
+			const kv = await fresh();
+			await kv.set("k", null);
+			expect(await kv.get("k")).toBeNull();
+			expect(await kv.list()).toEqual(["k"]);
+		});
+		it("lists keys sorted by code point, with an optional prefix", async () => {
+			const kv = await fresh();
+			for (const key of [
+				"b",
+				"a/2",
+				"a/10",
+				"a/1",
+				"ab",
+				"B",
+				"a"
+			]) await kv.set(key, key);
+			expect(await kv.list()).toEqual([
+				"B",
+				"a",
+				"a/1",
+				"a/10",
+				"a/2",
+				"ab",
+				"b"
+			]);
+			expect(await kv.list("a/")).toEqual([
+				"a/1",
+				"a/10",
+				"a/2"
+			]);
+			expect(await kv.list("a")).toEqual([
+				"a",
+				"a/1",
+				"a/10",
+				"a/2",
+				"ab"
+			]);
+			expect(await kv.list("")).toEqual([
+				"B",
+				"a",
+				"a/1",
+				"a/10",
+				"a/2",
+				"ab",
+				"b"
+			]);
+			expect(await kv.list("nothing")).toEqual([]);
+			expect(await kv.list(void 0)).toEqual(await kv.list());
+		});
+		it("orders astral characters after the rest of the basic plane, as code points", async () => {
+			const kv = await fresh();
+			for (const key of [
+				"😀",
+				"～",
+				"z",
+				""
+			]) await kv.set(key, 1);
+			expect(await kv.list()).toEqual([
+				"z",
+				"",
+				"～",
+				"😀"
+			]);
+		});
+		it("treats % _ \\ and letter case in a prefix as plain characters", async () => {
+			const kv = await fresh();
+			for (const key of [
+				"100%",
+				"100x",
+				"a_b",
+				"axb",
+				"Abc",
+				"abc",
+				"back\\slash",
+				"backXslash"
+			]) await kv.set(key, 1);
+			expect(await kv.list("100%")).toEqual(["100%"]);
+			expect(await kv.list("a_")).toEqual(["a_b"]);
+			expect(await kv.list("ab")).toEqual(["abc"]);
+			expect(await kv.list("Ab")).toEqual(["Abc"]);
+			expect(await kv.list("back\\")).toEqual(["back\\slash"]);
+			expect(await kv.list("😀")).toEqual([]);
+		});
+		it("updates a missing key from undefined, and a present one from its value, resolving the new value", async () => {
+			const kv = await fresh();
+			expect(await kv.update("n", (current) => (current ?? 0) + 1)).toBe(1);
+			expect(await kv.update("n", (current) => (current ?? 0) + 10)).toBe(11);
+			expect(await kv.get("n")).toBe(11);
+			expect(await kv.update("list", (current) => [...current ?? [], "a"])).toEqual(["a"]);
+		});
+		it("counts fifty concurrent updates to exactly fifty", async () => {
+			const kv = await fresh();
+			await Promise.all(Array.from({ length: 50 }, () => kv.update("counter", (current) => (current ?? 0) + 1)));
+			expect(await kv.get("counter")).toBe(50);
+		});
+		it("keeps updates of different keys independent, and a set between two updates in order", async () => {
+			const kv = await fresh();
+			const results = await Promise.all([
+				kv.update("a", (current) => (current ?? 0) + 1),
+				kv.set("a", 100),
+				kv.update("a", (current) => (current ?? 0) + 1),
+				kv.update("b", (current) => (current ?? 0) + 5)
+			]);
+			expect(results[0]).toBe(1);
+			expect(results[2]).toBe(101);
+			expect(await kv.get("a")).toBe(101);
+			expect(await kv.get("b")).toBe(5);
+		});
+		it("leaves the value as it was when the update callback throws, and rejects with its error", async () => {
+			const kv = await fresh();
+			await kv.set("k", "before");
+			const failure = /* @__PURE__ */ new Error("stop");
+			await expect(kv.update("k", () => {
+				throw failure;
+			})).rejects.toBe(failure);
+			expect(await kv.get("k")).toBe("before");
+			await expect(kv.update("absent", () => {
+				throw failure;
+			})).rejects.toBe(failure);
+			expect(await kv.get("absent")).toBeUndefined();
+		});
+		it("leaves the value as it was when the update returns something that is not JSON", async () => {
+			const kv = await fresh();
+			await kv.set("k", "before");
+			await expect(kv.update("k", () => void 0)).rejects.toThrow(TypeError);
+			await expect(kv.update("k", () => NaN)).rejects.toThrow(TypeError);
+			expect(await kv.get("k")).toBe("before");
+		});
+		it("rejects an update callback that returns a promise, with a message that says what to do, and keeps the value", async () => {
+			const kv = await fresh();
+			await kv.set("k", 1);
+			const asynchronous = (async () => 2);
+			await expect(kv.update("k", asynchronous)).rejects.toThrow(/synchronous/u);
+			expect(await kv.get("k")).toBe(1);
+			await kv.update("k", (current) => (current ?? 0) + 1);
+			expect(await kv.get("k")).toBe(2);
+		});
+		it("refuses an empty or non-string key on every call, and writes nothing", async () => {
+			const kv = await fresh();
+			for (const key of [
+				"",
+				1,
+				null,
+				void 0,
+				{}
+			]) {
+				await expect(kv.get(key)).rejects.toThrow(TypeError);
+				await expect(kv.set(key, 1)).rejects.toThrow(TypeError);
+				await expect(kv.update(key, () => 1)).rejects.toThrow(TypeError);
+				await expect(kv.delete(key)).rejects.toThrow(TypeError);
+			}
+			expect(await kv.list()).toEqual([]);
+		});
+		it("refuses a value that is not JSON with a TypeError, and writes nothing", async () => {
+			const kv = await fresh();
+			const circular = {};
+			circular.self = circular;
+			for (const value of [
+				void 0,
+				() => 1,
+				Symbol("s"),
+				1n,
+				NaN,
+				Number.POSITIVE_INFINITY,
+				circular,
+				{ deep: [Number.NEGATIVE_INFINITY] }
+			]) await expect(kv.set("k", value), String(value)).rejects.toThrow(TypeError);
+			expect(await kv.list()).toEqual([]);
+			await kv.set("k", "kept");
+			await expect(kv.set("k", void 0)).rejects.toThrow(TypeError);
+			expect(await kv.get("k")).toBe("kept");
+		});
+		it("hands out copies: changing what get returned, or the value after set, changes nothing stored", async () => {
+			const kv = await fresh();
+			const original = {
+				list: [1, 2],
+				nested: { n: 1 }
+			};
+			await kv.set("k", original);
+			original.list.push(3);
+			const first = await kv.get("k");
+			expect(first).toEqual({
+				list: [1, 2],
+				nested: { n: 1 }
+			});
+			first.nested.n = 99;
+			expect(await kv.get("k")).toEqual({
+				list: [1, 2],
+				nested: { n: 1 }
+			});
+			(await kv.update("k", (current) => {
+				current.list.push(4);
+				return current;
+			})).list.push(5);
+			expect(await kv.get("k")).toEqual({
+				list: [
+					1,
+					2,
+					4
+				],
+				nested: { n: 1 }
+			});
+		});
+		it("stores a value of a megabyte", async () => {
+			const kv = await fresh();
+			const big = "x".repeat(1024 * 1024);
+			await kv.set("big", { big });
+			expect((await kv.get("big"))?.big.length).toBe(big.length);
+		});
+		it("keeps what was written across close and reopen, and keeps a deleted key deleted", async () => {
+			const first = track(await open());
+			await first.kv.set("a", { n: 1 });
+			await first.kv.set("b", "two");
+			await first.kv.update("count", (current) => (current ?? 0) + 1);
+			await first.kv.set("gone", 1);
+			await first.kv.delete("gone");
+			const second = track(await first.reopen());
+			expect(await second.kv.list()).toEqual([
+				"a",
+				"b",
+				"count"
+			]);
+			expect(await second.kv.get("a")).toEqual({ n: 1 });
+			expect(await second.kv.get("count")).toBe(1);
+			expect(await second.kv.get("gone")).toBeUndefined();
+		});
+		it("rejects calls after close, and closing twice does nothing", async () => {
+			const subject = track(await open());
+			await subject.kv.set("k", 1);
+			await subject.close();
+			await subject.close();
+			await expect(subject.kv.get("k")).rejects.toThrow();
+			await expect(subject.kv.set("k", 2)).rejects.toThrow();
+		});
+		it("waits for writes still in flight when it closes", async () => {
+			const subject = track(await open());
+			const writes = Array.from({ length: 20 }, (_, index) => subject.kv.set(`k${String(index).padStart(2, "0")}`, index));
+			await subject.close();
+			await Promise.all(writes);
+			expect(await track(await subject.reopen()).kv.list()).toHaveLength(20);
+		});
+	});
+}
+//#endregion
+export { describeKvConformance };

package/lib/kv/db.d.ts

@@ -1,5 +1,5 @@
-import { s as Db } from "../index-D4FAsBZu.js";
-import { f as Kv } from "../index-BLTYsyc1.js";
+import { t as Db } from "../database-DBHdwefi.js";
+import { n as Kv } from "../kv-9f-AlRKN.js";
 
 //#region ../../plugins/acryl-kv-db/src/open.d.ts
 interface KvOnDbOptions {

package/lib/kv/json.d.ts

@@ -1,4 +1,4 @@
-import { f as Kv, p as KvOpened } from "../index-BLTYsyc1.js";
+import { n as Kv, r as KvOpened } from "../kv-9f-AlRKN.js";
 
 //#region ../../plugins/acryl-kv-json/src/open.d.ts
 interface OpenKvOptions {

package/lib/kv-9f-AlRKN.d.ts

@@ -0,0 +1,39 @@
+//#region ../../plugins/acryl-kv/src/kv.d.ts
+/** `T`, except a promise: the callback of `update` is synchronous, and an async one is a type error. */
+type NotPromise<T> = T extends PromiseLike<unknown> ? never : T;
+/** Anything JSON can hold. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * Named JSON documents. Every call returns a promise, so a file, SQLite and Postgres answer alike.
+ *
+ * Keys are non-empty strings. Values are JSON: `undefined`, functions, symbols, bigints and non-finite numbers are refused with a
+ * `TypeError` before anything is written, and a value read back is a copy.
+ *
+ * There is no `close`: the code that opened a store closes it (see {@link KvOpened}), so a plugin cannot close the store another uses.
+ */
+interface Kv {
+  /** The value stored under the key, or `undefined`. */
+  get<T = JsonValue>(key: string): Promise<T | undefined>;
+  /** Store a value under the key, replacing any. Resolves once it is durable. */
+  set<T = JsonValue>(key: string, value: T): Promise<void>;
+  /**
+   * Replace the value under the key by `change(current)`, atomically: `current` is `undefined` when the key is missing, `change` is
+   * synchronous (an `async` function is a type error, and a returned promise is rejected at run time: read what you need first, then update), and no other write to the key happens between reading it and writing the result. Resolves the new value. A `change` that
+   * throws, or returns something that is not JSON, leaves the value as it was and rejects with its error.
+   */
+  update<T = JsonValue>(key: string, change: (current: T | undefined) => NotPromise<T>): Promise<T>;
+  /** Remove the key. A missing key is not an error. */
+  delete(key: string): Promise<void>;
+  /** The keys that start with the prefix (all of them without one), sorted by code point (the order of their UTF-8 bytes, not of UTF-16 units). */
+  list(prefix?: string): Promise<string[]>;
+}
+/** An open store and the one function that closes it. */
+interface KvOpened {
+  readonly kv: Kv;
+  /** Waits for the writes in flight, then releases the storage. Calling it again does nothing; calls on `kv` after it reject. */
+  close(): Promise<void>;
+}
+//#endregion
+export { NotPromise as i, Kv as n, KvOpened as r, JsonValue as t };

package/lib/kv.d.ts

@@ -1,2 +1,3 @@
-import { a as checkKey, c as decodeValue, d as JsonValue, f as Kv, i as copyKv, l as encodeValue, m as NotPromise, n as CopyKvOptions, o as codePoints, p as KvOpened, r as CopyKvResult, s as compareKeys, t as KV_SERVICE, u as runChange } from "./index-BLTYsyc1.js";
+import { i as NotPromise, n as Kv, r as KvOpened, t as JsonValue } from "./kv-9f-AlRKN.js";
+import { a as checkKey, c as decodeValue, i as copyKv, l as encodeValue, n as CopyKvOptions, o as codePoints, r as CopyKvResult, s as compareKeys, t as KV_SERVICE, u as runChange } from "./index-BnGgRKTv.js";
 export { type CopyKvOptions, type CopyKvResult, type JsonValue, KV_SERVICE, type Kv, type KvOpened, type NotPromise, checkKey, codePoints, compareKeys, copyKv, decodeValue, encodeValue, runChange };

package/lib/language-D9a4zqvn.js

@@ -0,0 +1,198 @@
+import { parseAccept } from "./utils/accept.js";
+import { getCookie, setCookie } from "./cookie.js";
+//#region ../../plugins/acryl-router/src/core/middleware/language/language.ts
+const DEFAULT_OPTIONS = {
+	order: [
+		"querystring",
+		"cookie",
+		"header"
+	],
+	lookupQueryString: "lang",
+	lookupCookie: "language",
+	lookupFromHeaderKey: "accept-language",
+	lookupFromPathIndex: 0,
+	caches: ["cookie"],
+	ignoreCase: true,
+	fallbackLanguage: "en",
+	supportedLanguages: ["en"],
+	cookieOptions: {
+		sameSite: "Strict",
+		secure: true,
+		maxAge: 365 * 24 * 60 * 60,
+		httpOnly: true
+	},
+	debug: false
+};
+/**
+* Parse Accept-Language header values with quality scores
+* @param header Accept-Language header string
+* @returns Array of parsed languages with quality scores
+*/
+function parseAcceptLanguage(header) {
+	return parseAccept(header).map(({ type, q }) => ({
+		lang: type,
+		q
+	}));
+}
+/**
+* Validate and normalize language codes
+* @param lang Language code to normalize
+* @param options Detector options
+* @returns Normalized language code or undefined
+*/
+const normalizeLanguage = (lang, options) => {
+	if (!lang) return;
+	try {
+		let normalizedLang = lang.trim();
+		if (options.convertDetectedLanguage) normalizedLang = options.convertDetectedLanguage(normalizedLang);
+		const compLang = options.ignoreCase ? normalizedLang.toLowerCase() : normalizedLang;
+		const compSupported = options.supportedLanguages.map((l) => options.ignoreCase ? l.toLowerCase() : l);
+		const exactIndex = compSupported.indexOf(compLang);
+		if (exactIndex !== -1) return options.supportedLanguages[exactIndex];
+		let longestMatchIndex = -1;
+		let longestMatchLength = -1;
+		for (let i = 0; i < compSupported.length; i++) {
+			const candidate = compSupported[i];
+			if (candidate.length < compLang.length && candidate.length > longestMatchLength && compLang.startsWith(candidate) && compLang[candidate.length] === "-") {
+				longestMatchIndex = i;
+				longestMatchLength = candidate.length;
+			}
+		}
+		if (longestMatchIndex !== -1) return options.supportedLanguages[longestMatchIndex];
+		return;
+	} catch {
+		return;
+	}
+};
+/**
+* Detects language from query parameter
+*/
+const detectFromQuery = (c, options) => {
+	const query = c.req.query(options.lookupQueryString);
+	return normalizeLanguage(query, options);
+};
+/**
+* Detects language from cookie
+*/
+const detectFromCookie = (c, options) => {
+	const cookie = getCookie(c, options.lookupCookie);
+	return normalizeLanguage(cookie, options);
+};
+/**
+* Detects language from Accept-Language header
+*/
+function detectFromHeader(c, options) {
+	try {
+		const acceptLanguage = c.req.header(options.lookupFromHeaderKey);
+		if (!acceptLanguage) return;
+		const languages = parseAcceptLanguage(acceptLanguage);
+		for (const { lang, q } of languages) {
+			if (q === 0) continue;
+			const normalizedLang = normalizeLanguage(lang, options);
+			if (normalizedLang) return normalizedLang;
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+/**
+* Detects language from URL path
+*/
+function detectFromPath(c, options) {
+	const langSegment = new URL(c.req.url).pathname.split("/").filter(Boolean)[options.lookupFromPathIndex];
+	return normalizeLanguage(langSegment, options);
+}
+/**
+* Collection of all language detection strategies
+*/
+const detectors = {
+	querystring: detectFromQuery,
+	cookie: detectFromCookie,
+	header: detectFromHeader,
+	path: detectFromPath
+};
+/**
+* Validate detector options
+* @param options Detector options to validate
+* @throws Error if options are invalid
+*/
+function validateOptions(options) {
+	if (!options.supportedLanguages.includes(options.fallbackLanguage)) throw new Error("Fallback language must be included in supported languages");
+	if (options.lookupFromPathIndex < 0) throw new Error("Path index must be non-negative");
+	if (!options.order.every((detector) => Object.keys(detectors).includes(detector))) throw new Error("Invalid detector type in order array");
+}
+/**
+* Cache detected language
+*/
+function cacheLanguage(c, language, options) {
+	if (!Array.isArray(options.caches) || !options.caches.includes("cookie")) return;
+	try {
+		setCookie(c, options.lookupCookie, language, options.cookieOptions);
+	} catch (error) {
+		if (options.debug) console.error("Failed to cache language:", error);
+	}
+}
+/**
+* Detect language from request
+*/
+const detectLanguage = (c, options) => {
+	let detectedLang;
+	for (const detectorName of options.order) {
+		const detector = detectors[detectorName];
+		try {
+			detectedLang = detector(c, options);
+			if (detectedLang) {
+				if (options.debug) console.log(`Language detected from ${detectorName}: ${detectedLang}`);
+				break;
+			}
+		} catch (error) {
+			if (options.debug) console.error(`Error in ${detectorName} detector:`, error);
+			continue;
+		}
+	}
+	const finalLang = detectedLang || options.fallbackLanguage;
+	if (detectedLang && options.caches) cacheLanguage(c, finalLang, options);
+	return finalLang;
+};
+/**
+* Language detector middleware factory
+* @param userOptions Configuration options for the language detector
+* @returns Acryl middleware function
+*
+* @example
+* ```ts
+* type Variables = LanguageVariables
+* const app = new Acryl<{ Variables: Variables }>()
+*
+* app.use(
+*   languageDetector({
+*     supportedLanguages: ['en', 'ja'], // Must include fallback
+*     fallbackLanguage: 'en', // Required
+*   })
+* )
+*
+* app.get('/', (c) => {
+*   const lang = c.get('language')
+*   return c.text(`Current language: ${lang}`)
+* })
+* ```
+*/
+const languageDetector = (userOptions) => {
+	const options = {
+		...DEFAULT_OPTIONS,
+		...userOptions,
+		cookieOptions: {
+			...DEFAULT_OPTIONS.cookieOptions,
+			...userOptions.cookieOptions
+		}
+	};
+	validateOptions(options);
+	return async function languageDetector(ctx, next) {
+		const lang = detectLanguage(ctx, options);
+		ctx.set("language", lang);
+		await next();
+	};
+};
+//#endregion
+export { languageDetector as a, detectFromQuery as i, detectFromHeader as n, detectFromPath as r, detectFromCookie as t };