@elurjs/kit 2.4.10 → 2.5.1

package/dist/lib/cache/index.js

@@ -0,0 +1,113 @@
+import { a as e, i as t, n, o as r, r as i, t as a } from "../invalidation-DXhdE9wj.js";
+import { i as o, n as s, r as c, t as l } from "../cache-DGhTYyqh.js";
+import { i as u, n as d, r as f } from "../adapter-DNsjXvq5.js";
+//#region src/cache/redis-adapter.ts
+function p(e) {
+	let t = e.client, n = e.prefix ?? "elur-kit:", r = (e) => `${n}data:${e}`, i = (e) => `${n}tag:${e}`;
+	async function a(e) {
+		let n = await t.get(r(e));
+		if (!n) return null;
+		try {
+			return JSON.parse(n);
+		} catch {
+			return null;
+		}
+	}
+	async function o(e, n, a) {
+		let o = {
+			html: n.html,
+			generatedAt: n.generatedAt ?? Date.now(),
+			revalidate: a.revalidate,
+			tags: a.tags,
+			version: a.version
+		}, s = r(e), c = JSON.stringify(o);
+		if (a.revalidate > 0 ? await t.set(s, c, { PX: a.revalidate * 1e3 }) : await t.set(s, c), a.tags && a.tags.length > 0 && t.sadd && t.srem) for (let e of a.tags) await t.sadd(i(e), s);
+	}
+	async function s(e) {
+		await t.del(r(e));
+	}
+	async function c(e) {
+		if (e.length !== 0) {
+			if (t.smembers && t.srem) {
+				let n = /* @__PURE__ */ new Set();
+				for (let r of e) {
+					let e = await t.smembers(i(r));
+					for (let t of e) n.add(t);
+					await t.del(i(r));
+				}
+				n.size > 0 && await t.del([...n]);
+			} else {
+				let r = await t.keys(`${n}data:*`);
+				for (let n of r) {
+					let r = await t.get(n);
+					if (r) try {
+						JSON.parse(r).tags?.some((t) => e.includes(t)) && await t.del(n);
+					} catch {}
+				}
+			}
+		}
+	}
+	return {
+		get: a,
+		set: o,
+		delete: s,
+		invalidateTags: c
+	};
+}
+function m(e) {
+	let t = e.namespace, n = e.prefix ?? "elur-kit:", r = (e) => `${n}data:${e}`, i = (e) => `${n}tag:${e}`;
+	async function a(e) {
+		let n = await t.get(i(e));
+		if (!n) return [];
+		try {
+			return JSON.parse(n);
+		} catch {
+			return [];
+		}
+	}
+	async function o(e, n) {
+		await t.put(i(e), JSON.stringify(n));
+	}
+	async function s(e) {
+		let n = await t.get(r(e));
+		if (!n) return null;
+		try {
+			return JSON.parse(n);
+		} catch {
+			return null;
+		}
+	}
+	async function c(e, n, i) {
+		let s = {
+			html: n.html,
+			generatedAt: n.generatedAt ?? Date.now(),
+			revalidate: i.revalidate,
+			tags: i.tags,
+			version: i.version
+		}, c = r(e), l = JSON.stringify(s);
+		if (i.revalidate > 0 ? await t.put(c, l, { expirationTtl: i.revalidate }) : await t.put(c, l), i.tags && i.tags.length > 0) for (let e of i.tags) {
+			let t = await a(e);
+			t.includes(c) || (t.push(c), await o(e, t));
+		}
+	}
+	async function l(e) {
+		await t.delete(r(e));
+	}
+	async function u(e) {
+		if (e.length !== 0) for (let n of e) {
+			let e = await a(n);
+			for (let n of e) await t.delete(n);
+			await t.delete(i(n));
+		}
+	}
+	return {
+		get: s,
+		set: c,
+		delete: l,
+		invalidateTags: u
+	};
+}
+//#endregion
+export { a as CacheInvalidator, t as DEFAULT_CACHE_POLICY, d as cacheKey, l as clearCache, n as connectCacheAdapter, m as createCloudflareKVCacheAdapter, f as createFsCacheAdapter, p as createRedisCacheAdapter, i as defaultInvalidator, s as getCachedHtml, u as getWithSWR, c as isStale, e as normalizeCachePolicy, o as setCachedHtml, r as shouldCachePublic };
+
+//# sourceMappingURL=index.js.map

package/dist/lib/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/cache/redis-adapter.ts"],"sourcesContent":["// --- Redis / Upstash / Cloudflare KV Cache Adapter (v2.1 — Fix #3) ---\n//\n// Pluggable cache adapter for serverless and distributed deployments.\n// Implements the same CacheAdapter interface as the filesystem adapter, so\n// it can be dropped in via config without changing application code.\n//\n// Supports any Redis-compatible client (node-redis, ioredis, Upstash REST,\n// Cloudflare KV via @upstash/redis or direct API).\n\nimport type { CacheAdapter, CacheEntry, CacheWriteOptions } from \"./adapter.js\";\n\n// ─── Redis Cache Adapter ────────────────────────────────────────────────────\n\nexport interface RedisCacheAdapterOptions {\n  /**\n   * Redis client with get/set/del commands.\n   * Compatible with node-redis, ioredis, and Upstash.\n   */\n  client: RedisClient;\n  /** Key prefix to namespace cache entries. Default: \"elur-kit:\". */\n  prefix?: string;\n}\n\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, opts?: { EX?: number; PX?: number; NX?: boolean }): Promise<unknown>;\n  del(key: string | string[]): Promise<number>;\n  keys(pattern: string): Promise<string[]>;\n  srem?(key: string, ...members: string[]): Promise<number>;\n  smembers?(key: string): Promise<string[]>;\n  sadd?(key: string, ...members: string[]): Promise<number>;\n}\n\nexport function createRedisCacheAdapter(options: RedisCacheAdapterOptions): CacheAdapter {\n  const client = options.client;\n  const prefix = options.prefix ?? \"elur-kit:\";\n\n  const dataKey = (key: string) => `${prefix}data:${key}`;\n  const tagKey = (tag: string) => `${prefix}tag:${tag}`;\n\n  async function get(key: string): Promise<CacheEntry | null> {\n    const raw = await client.get(dataKey(key));\n    if (!raw) return null;\n    try {\n      return JSON.parse(raw) as CacheEntry;\n    } catch {\n      return null;\n    }\n  }\n\n  async function set(key: string, value: CacheEntry, opts: CacheWriteOptions): Promise<void> {\n    const entry: CacheEntry = {\n      html: value.html,\n      generatedAt: value.generatedAt ?? Date.now(),\n      revalidate: opts.revalidate,\n      tags: opts.tags,\n      version: opts.version,\n    };\n    const fullKey = dataKey(key);\n    const serialized = JSON.stringify(entry);\n\n    // Set TTL on the Redis key if revalidate is set (convert seconds to ms for PX).\n    if (opts.revalidate > 0) {\n      await client.set(fullKey, serialized, { PX: opts.revalidate * 1000 });\n    } else {\n      await client.set(fullKey, serialized);\n    }\n\n    // Update tag index using Redis sets if available.\n    if (opts.tags && opts.tags.length > 0 && client.sadd && client.srem) {\n      for (const tag of opts.tags) {\n        await client.sadd(tagKey(tag), fullKey);\n      }\n    }\n  }\n\n  async function del(key: string): Promise<void> {\n    await client.del(dataKey(key));\n  }\n\n  async function invalidateTags(tags: readonly string[]): Promise<void> {\n    if (tags.length === 0) return;\n\n    if (client.smembers && client.srem) {\n      // Use Redis sets for O(1) tag lookup.\n      const keysToDelete = new Set<string>();\n      for (const tag of tags) {\n        const members = await client.smembers(tagKey(tag));\n        for (const m of members) keysToDelete.add(m);\n        await client.del(tagKey(tag));\n      }\n      if (keysToDelete.size > 0) {\n        await client.del([...keysToDelete]);\n      }\n    } else {\n      // Fallback: scan all data keys and check tags in the entry.\n      const allKeys = await client.keys(`${prefix}data:*`);\n      for (const fullKey of allKeys) {\n        const raw = await client.get(fullKey);\n        if (!raw) continue;\n        try {\n          const entry = JSON.parse(raw) as CacheEntry;\n          if (entry.tags?.some((t) => tags.includes(t))) {\n            await client.del(fullKey);\n          }\n        } catch {\n          // skip corrupt entries\n        }\n      }\n    }\n  }\n\n  return { get, set, delete: del, invalidateTags };\n}\n\n// ─── Cloudflare KV Cache Adapter ────────────────────────────────────────────\n\nexport interface CloudflareKVAdapterOptions {\n  /**\n   * Cloudflare KV namespace binding (from wrangler.toml env binding).\n   * Must implement `get`, `put`, and `delete` methods.\n   */\n  namespace: CloudflareKVNamespace;\n  /** Key prefix to namespace cache entries. Default: \"elur-kit:\". */\n  prefix?: string;\n}\n\nexport interface CloudflareKVNamespace {\n  get(key: string): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n  list(options?: { prefix?: string }): Promise<{ keys: { name: string; metadata?: unknown }[] }>;\n}\n\nexport function createCloudflareKVCacheAdapter(options: CloudflareKVAdapterOptions): CacheAdapter {\n  const kv = options.namespace;\n  const prefix = options.prefix ?? \"elur-kit:\";\n\n  const dataKey = (key: string) => `${prefix}data:${key}`;\n  const tagKey = (tag: string) => `${prefix}tag:${tag}`;\n\n  // KV doesn't have sets, so we store tag → keys as a JSON string.\n  async function loadTagKeys(tag: string): Promise<string[]> {\n    const raw = await kv.get(tagKey(tag));\n    if (!raw) return [];\n    try {\n      return JSON.parse(raw) as string[];\n    } catch {\n      return [];\n    }\n  }\n\n  async function saveTagKeys(tag: string, keys: string[]): Promise<void> {\n    await kv.put(tagKey(tag), JSON.stringify(keys));\n  }\n\n  async function get(key: string): Promise<CacheEntry | null> {\n    const raw = await kv.get(dataKey(key));\n    if (!raw) return null;\n    try {\n      return JSON.parse(raw) as CacheEntry;\n    } catch {\n      return null;\n    }\n  }\n\n  async function set(key: string, value: CacheEntry, opts: CacheWriteOptions): Promise<void> {\n    const entry: CacheEntry = {\n      html: value.html,\n      generatedAt: value.generatedAt ?? Date.now(),\n      revalidate: opts.revalidate,\n      tags: opts.tags,\n      version: opts.version,\n    };\n    const fullKey = dataKey(key);\n    const serialized = JSON.stringify(entry);\n\n    // KV supports expirationTtl in seconds.\n    if (opts.revalidate > 0) {\n      await kv.put(fullKey, serialized, { expirationTtl: opts.revalidate });\n    } else {\n      await kv.put(fullKey, serialized);\n    }\n\n    // Update tag index.\n    if (opts.tags && opts.tags.length > 0) {\n      for (const tag of opts.tags) {\n        const existing = await loadTagKeys(tag);\n        if (!existing.includes(fullKey)) {\n          existing.push(fullKey);\n          await saveTagKeys(tag, existing);\n        }\n      }\n    }\n  }\n\n  async function del(key: string): Promise<void> {\n    await kv.delete(dataKey(key));\n  }\n\n  async function invalidateTags(tags: readonly string[]): Promise<void> {\n    if (tags.length === 0) return;\n    for (const tag of tags) {\n      const keys = await loadTagKeys(tag);\n      for (const fullKey of keys) {\n        await kv.delete(fullKey);\n      }\n      await kv.delete(tagKey(tag));\n    }\n  }\n\n  return { get, set, delete: del, invalidateTags };\n}\n"],"mappings":"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"}

package/dist/lib/cache/invalidation.d.cts

@@ -0,0 +1,36 @@
+export interface InvalidationEvent {
+    tags?: readonly string[];
+    paths?: readonly string[];
+    /** Source of the invalidation (e.g. action name). */
+    source?: string;
+}
+export type InvalidationListener = (event: InvalidationEvent) => void | Promise<void>;
+/**
+ * A pub/sub hub for cache invalidation events. Actions emit events;
+ * the cache adapter (and optionally elur-query or other integrations) listen.
+ */
+export declare class CacheInvalidator {
+    private listeners;
+    /** Registers a listener for invalidation events. Returns an unsubscribe function. */
+    on(listener: InvalidationListener): () => void;
+    /** Emits an invalidation event to all listeners. */
+    emit(event: InvalidationEvent): Promise<void>;
+    /** Convenience: invalidate by tags. */
+    invalidateTags(tags: readonly string[], source?: string): Promise<void>;
+    /** Convenience: invalidate by paths. */
+    invalidatePaths(paths: readonly string[], source?: string): Promise<void>;
+    /** Removes all listeners. */
+    clear(): void;
+}
+/** Global default invalidator. The runtime registers the cache adapter here. */
+export declare const defaultInvalidator: CacheInvalidator;
+/**
+ * Connects a CacheAdapter to the default invalidator so that tag/path
+ * invalidation events from actions are dispatched to the cache.
+ *
+ * Returns an unsubscribe function.
+ */
+export declare function connectCacheAdapter(adapter: {
+    invalidateTags: (tags: readonly string[]) => Promise<void>;
+    delete?: (key: string) => Promise<void>;
+}, invalidator?: CacheInvalidator): () => void;

package/dist/lib/cache/invalidation.d.ts

@@ -0,0 +1,36 @@
+export interface InvalidationEvent {
+    tags?: readonly string[];
+    paths?: readonly string[];
+    /** Source of the invalidation (e.g. action name). */
+    source?: string;
+}
+export type InvalidationListener = (event: InvalidationEvent) => void | Promise<void>;
+/**
+ * A pub/sub hub for cache invalidation events. Actions emit events;
+ * the cache adapter (and optionally elur-query or other integrations) listen.
+ */
+export declare class CacheInvalidator {
+    private listeners;
+    /** Registers a listener for invalidation events. Returns an unsubscribe function. */
+    on(listener: InvalidationListener): () => void;
+    /** Emits an invalidation event to all listeners. */
+    emit(event: InvalidationEvent): Promise<void>;
+    /** Convenience: invalidate by tags. */
+    invalidateTags(tags: readonly string[], source?: string): Promise<void>;
+    /** Convenience: invalidate by paths. */
+    invalidatePaths(paths: readonly string[], source?: string): Promise<void>;
+    /** Removes all listeners. */
+    clear(): void;
+}
+/** Global default invalidator. The runtime registers the cache adapter here. */
+export declare const defaultInvalidator: CacheInvalidator;
+/**
+ * Connects a CacheAdapter to the default invalidator so that tag/path
+ * invalidation events from actions are dispatched to the cache.
+ *
+ * Returns an unsubscribe function.
+ */
+export declare function connectCacheAdapter(adapter: {
+    invalidateTags: (tags: readonly string[]) => Promise<void>;
+    delete?: (key: string) => Promise<void>;
+}, invalidator?: CacheInvalidator): () => void;

package/dist/lib/cache/redis-adapter.d.cts

@@ -0,0 +1,49 @@
+import type { CacheAdapter } from "./adapter.js";
+export interface RedisCacheAdapterOptions {
+    /**
+     * Redis client with get/set/del commands.
+     * Compatible with node-redis, ioredis, and Upstash.
+     */
+    client: RedisClient;
+    /** Key prefix to namespace cache entries. Default: "elur-kit:". */
+    prefix?: string;
+}
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, opts?: {
+        EX?: number;
+        PX?: number;
+        NX?: boolean;
+    }): Promise<unknown>;
+    del(key: string | string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    srem?(key: string, ...members: string[]): Promise<number>;
+    smembers?(key: string): Promise<string[]>;
+    sadd?(key: string, ...members: string[]): Promise<number>;
+}
+export declare function createRedisCacheAdapter(options: RedisCacheAdapterOptions): CacheAdapter;
+export interface CloudflareKVAdapterOptions {
+    /**
+     * Cloudflare KV namespace binding (from wrangler.toml env binding).
+     * Must implement `get`, `put`, and `delete` methods.
+     */
+    namespace: CloudflareKVNamespace;
+    /** Key prefix to namespace cache entries. Default: "elur-kit:". */
+    prefix?: string;
+}
+export interface CloudflareKVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+    }): Promise<{
+        keys: {
+            name: string;
+            metadata?: unknown;
+        }[];
+    }>;
+}
+export declare function createCloudflareKVCacheAdapter(options: CloudflareKVAdapterOptions): CacheAdapter;

package/dist/lib/cache/redis-adapter.d.ts

@@ -0,0 +1,49 @@
+import type { CacheAdapter } from "./adapter.js";
+export interface RedisCacheAdapterOptions {
+    /**
+     * Redis client with get/set/del commands.
+     * Compatible with node-redis, ioredis, and Upstash.
+     */
+    client: RedisClient;
+    /** Key prefix to namespace cache entries. Default: "elur-kit:". */
+    prefix?: string;
+}
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, opts?: {
+        EX?: number;
+        PX?: number;
+        NX?: boolean;
+    }): Promise<unknown>;
+    del(key: string | string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    srem?(key: string, ...members: string[]): Promise<number>;
+    smembers?(key: string): Promise<string[]>;
+    sadd?(key: string, ...members: string[]): Promise<number>;
+}
+export declare function createRedisCacheAdapter(options: RedisCacheAdapterOptions): CacheAdapter;
+export interface CloudflareKVAdapterOptions {
+    /**
+     * Cloudflare KV namespace binding (from wrangler.toml env binding).
+     * Must implement `get`, `put`, and `delete` methods.
+     */
+    namespace: CloudflareKVNamespace;
+    /** Key prefix to namespace cache entries. Default: "elur-kit:". */
+    prefix?: string;
+}
+export interface CloudflareKVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+    }): Promise<{
+        keys: {
+            name: string;
+            metadata?: unknown;
+        }[];
+    }>;
+}
+export declare function createCloudflareKVCacheAdapter(options: CloudflareKVAdapterOptions): CacheAdapter;

package/dist/lib/cache-DGhTYyqh.js

@@ -0,0 +1,50 @@
+import { mkdir as e, readFile as t, rename as n, rm as r, writeFile as i } from "node:fs/promises";
+import { dirname as a, join as o } from "node:path";
+import { createHash as s, randomUUID as c } from "node:crypto";
+//#region src/cache.ts
+function l(e, t) {
+	let n = s("sha256").update(t).digest("hex");
+	return o(e, `${n}.html.json`);
+}
+async function u(e, n) {
+	let r = l(e, n);
+	try {
+		let e = await t(r, "utf8"), n = JSON.parse(e);
+		if (Date.now() - n.generatedAt < n.revalidate * 1e3) return n;
+	} catch {}
+}
+async function d(t, o, s, u) {
+	let d = l(t, o);
+	await e(a(d), { recursive: !0 });
+	let f = {
+		html: s,
+		generatedAt: Date.now(),
+		revalidate: u
+	}, p = `${d}.${process.pid}.${c()}.tmp`;
+	try {
+		await i(p, JSON.stringify(f), "utf8"), await n(p, d);
+	} finally {
+		await r(p, { force: !0 });
+	}
+}
+async function f(e, n) {
+	let r = l(e, n);
+	try {
+		let e = await t(r, "utf8"), n = JSON.parse(e);
+		return Date.now() - n.generatedAt >= n.revalidate * 1e3;
+	} catch {
+		return !0;
+	}
+}
+async function p(e) {
+	try {
+		await r(e, {
+			recursive: !0,
+			force: !0
+		});
+	} catch {}
+}
+//#endregion
+export { d as i, u as n, f as r, p as t };
+
+//# sourceMappingURL=cache-DGhTYyqh.js.map

package/dist/lib/cache-DGhTYyqh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-DGhTYyqh.js","names":[],"sources":["../../src/cache.ts"],"sourcesContent":["import { mkdir, readFile, rename, rm, writeFile } from \"node:fs/promises\";\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { dirname, join } from \"node:path\";\n\nexport interface CacheEntry {\n  html: string;\n  generatedAt: number;\n  revalidate: number;\n}\n\nexport interface CacheOptions {\n  cacheDir: string;\n  defaultRevalidate?: number;\n}\n\nfunction cachePath(cacheDir: string, pathname: string): string {\n  const key = createHash(\"sha256\").update(pathname).digest(\"hex\");\n  return join(cacheDir, `${key}.html.json`);\n}\n\nexport async function getCachedHtml(\n  cacheDir: string,\n  pathname: string,\n): Promise<CacheEntry | undefined> {\n  const path = cachePath(cacheDir, pathname);\n  try {\n    const raw = await readFile(path, \"utf8\");\n    const entry = JSON.parse(raw) as CacheEntry;\n    if (Date.now() - entry.generatedAt < entry.revalidate * 1000) {\n      return entry;\n    }\n  } catch {\n    // cache miss or invalid\n  }\n  return undefined;\n}\n\nexport async function setCachedHtml(\n  cacheDir: string,\n  pathname: string,\n  html: string,\n  revalidate: number,\n): Promise<void> {\n  const path = cachePath(cacheDir, pathname);\n  await mkdir(dirname(path), { recursive: true });\n  const entry: CacheEntry = { html, generatedAt: Date.now(), revalidate };\n  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;\n  try {\n    await writeFile(temporaryPath, JSON.stringify(entry), \"utf8\");\n    await rename(temporaryPath, path);\n  } finally {\n    await rm(temporaryPath, { force: true });\n  }\n}\n\nexport async function isStale(cacheDir: string, pathname: string): Promise<boolean> {\n  const path = cachePath(cacheDir, pathname);\n  try {\n    const raw = await readFile(path, \"utf8\");\n    const entry = JSON.parse(raw) as CacheEntry;\n    return Date.now() - entry.generatedAt >= entry.revalidate * 1000;\n  } catch {\n    return true;\n  }\n}\n\nexport async function clearCache(cacheDir: string): Promise<void> {\n  try {\n    await rm(cacheDir, { recursive: true, force: true });\n  } catch {\n    // ignore\n  }\n}\n"],"mappings":";;;;AAeA,SAAS,EAAU,GAAkB,GAA0B;CAC7D,IAAM,IAAM,EAAW,QAAQ,CAAC,CAAC,OAAO,CAAQ,CAAC,CAAC,OAAO,KAAK;CAC9D,OAAO,EAAK,GAAU,GAAG,EAAI,WAAW;AAC1C;AAEA,eAAsB,EACpB,GACA,GACiC;CACjC,IAAM,IAAO,EAAU,GAAU,CAAQ;CACzC,IAAI;EACF,IAAM,IAAM,MAAM,EAAS,GAAM,MAAM,GACjC,IAAQ,KAAK,MAAM,CAAG;EAC5B,IAAI,KAAK,IAAI,IAAI,EAAM,cAAc,EAAM,aAAa,KACtD,OAAO;CAEX,QAAQ,CAER;AAEF;AAEA,eAAsB,EACpB,GACA,GACA,GACA,GACe;CACf,IAAM,IAAO,EAAU,GAAU,CAAQ;CACzC,MAAM,EAAM,EAAQ,CAAI,GAAG,EAAE,WAAW,GAAK,CAAC;CAC9C,IAAM,IAAoB;EAAE;EAAM,aAAa,KAAK,IAAI;EAAG;CAAW,GAChE,IAAgB,GAAG,EAAK,GAAG,QAAQ,IAAI,GAAG,EAAW,EAAE;CAC7D,IAAI;EAEF,AADA,MAAM,EAAU,GAAe,KAAK,UAAU,CAAK,GAAG,MAAM,GAC5D,MAAM,EAAO,GAAe,CAAI;CAClC,UAAU;EACR,MAAM,EAAG,GAAe,EAAE,OAAO,GAAK,CAAC;CACzC;AACF;AAEA,eAAsB,EAAQ,GAAkB,GAAoC;CAClF,IAAM,IAAO,EAAU,GAAU,CAAQ;CACzC,IAAI;EACF,IAAM,IAAM,MAAM,EAAS,GAAM,MAAM,GACjC,IAAQ,KAAK,MAAM,CAAG;EAC5B,OAAO,KAAK,IAAI,IAAI,EAAM,eAAe,EAAM,aAAa;CAC9D,QAAQ;EACN,OAAO;CACT;AACF;AAEA,eAAsB,EAAW,GAAiC;CAChE,IAAI;EACF,MAAM,EAAG,GAAU;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;CACrD,QAAQ,CAER;AACF"}

package/dist/lib/cache-X1n4Ossu.cjs

@@ -0,0 +1,2 @@
+let e=require("node:fs/promises"),t=require("node:path"),n=require("node:crypto");function r(e,r){let i=(0,n.createHash)(`sha256`).update(r).digest(`hex`);return(0,t.join)(e,`${i}.html.json`)}async function i(t,n){let i=r(t,n);try{let t=await(0,e.readFile)(i,`utf8`),n=JSON.parse(t);if(Date.now()-n.generatedAt<n.revalidate*1e3)return n}catch{}}async function a(i,a,o,s){let c=r(i,a);await(0,e.mkdir)((0,t.dirname)(c),{recursive:!0});let l={html:o,generatedAt:Date.now(),revalidate:s},u=`${c}.${process.pid}.${(0,n.randomUUID)()}.tmp`;try{await(0,e.writeFile)(u,JSON.stringify(l),`utf8`),await(0,e.rename)(u,c)}finally{await(0,e.rm)(u,{force:!0})}}async function o(t,n){let i=r(t,n);try{let t=await(0,e.readFile)(i,`utf8`),n=JSON.parse(t);return Date.now()-n.generatedAt>=n.revalidate*1e3}catch{return!0}}async function s(t){try{await(0,e.rm)(t,{recursive:!0,force:!0})}catch{}}Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return o}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return s}});
+//# sourceMappingURL=cache-X1n4Ossu.cjs.map

package/dist/lib/cache-X1n4Ossu.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-X1n4Ossu.cjs","names":[],"sources":["../../src/cache.ts"],"sourcesContent":["import { mkdir, readFile, rename, rm, writeFile } from \"node:fs/promises\";\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { dirname, join } from \"node:path\";\n\nexport interface CacheEntry {\n  html: string;\n  generatedAt: number;\n  revalidate: number;\n}\n\nexport interface CacheOptions {\n  cacheDir: string;\n  defaultRevalidate?: number;\n}\n\nfunction cachePath(cacheDir: string, pathname: string): string {\n  const key = createHash(\"sha256\").update(pathname).digest(\"hex\");\n  return join(cacheDir, `${key}.html.json`);\n}\n\nexport async function getCachedHtml(\n  cacheDir: string,\n  pathname: string,\n): Promise<CacheEntry | undefined> {\n  const path = cachePath(cacheDir, pathname);\n  try {\n    const raw = await readFile(path, \"utf8\");\n    const entry = JSON.parse(raw) as CacheEntry;\n    if (Date.now() - entry.generatedAt < entry.revalidate * 1000) {\n      return entry;\n    }\n  } catch {\n    // cache miss or invalid\n  }\n  return undefined;\n}\n\nexport async function setCachedHtml(\n  cacheDir: string,\n  pathname: string,\n  html: string,\n  revalidate: number,\n): Promise<void> {\n  const path = cachePath(cacheDir, pathname);\n  await mkdir(dirname(path), { recursive: true });\n  const entry: CacheEntry = { html, generatedAt: Date.now(), revalidate };\n  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;\n  try {\n    await writeFile(temporaryPath, JSON.stringify(entry), \"utf8\");\n    await rename(temporaryPath, path);\n  } finally {\n    await rm(temporaryPath, { force: true });\n  }\n}\n\nexport async function isStale(cacheDir: string, pathname: string): Promise<boolean> {\n  const path = cachePath(cacheDir, pathname);\n  try {\n    const raw = await readFile(path, \"utf8\");\n    const entry = JSON.parse(raw) as CacheEntry;\n    return Date.now() - entry.generatedAt >= entry.revalidate * 1000;\n  } catch {\n    return true;\n  }\n}\n\nexport async function clearCache(cacheDir: string): Promise<void> {\n  try {\n    await rm(cacheDir, { recursive: true, force: true });\n  } catch {\n    // ignore\n  }\n}\n"],"mappings":"kFAeA,SAAS,EAAU,EAAkB,EAA0B,CAC7D,IAAM,GAAA,EAAM,EAAA,WAAA,CAAW,QAAQ,CAAC,CAAC,OAAO,CAAQ,CAAC,CAAC,OAAO,KAAK,EAC9D,OAAA,EAAO,EAAA,KAAA,CAAK,EAAU,GAAG,EAAI,WAAW,CAC1C,CAEA,eAAsB,EACpB,EACA,EACiC,CACjC,IAAM,EAAO,EAAU,EAAU,CAAQ,EACzC,GAAI,CACF,IAAM,EAAM,MAAA,EAAM,EAAA,SAAA,CAAS,EAAM,MAAM,EACjC,EAAQ,KAAK,MAAM,CAAG,EAC5B,GAAI,KAAK,IAAI,EAAI,EAAM,YAAc,EAAM,WAAa,IACtD,OAAO,CAEX,MAAQ,CAER,CAEF,CAEA,eAAsB,EACpB,EACA,EACA,EACA,EACe,CACf,IAAM,EAAO,EAAU,EAAU,CAAQ,EACzC,MAAA,EAAM,EAAA,MAAA,EAAA,EAAM,EAAA,QAAA,CAAQ,CAAI,EAAG,CAAE,UAAW,EAAK,CAAC,EAC9C,IAAM,EAAoB,CAAE,OAAM,YAAa,KAAK,IAAI,EAAG,YAAW,EAChE,EAAgB,GAAG,EAAK,GAAG,QAAQ,IAAI,IAAA,EAAG,EAAA,WAAA,CAAW,EAAE,MAC7D,GAAI,CACF,MAAA,EAAM,EAAA,UAAA,CAAU,EAAe,KAAK,UAAU,CAAK,EAAG,MAAM,EAC5D,MAAA,EAAM,EAAA,OAAA,CAAO,EAAe,CAAI,CAClC,QAAU,CACR,MAAA,EAAM,EAAA,GAAA,CAAG,EAAe,CAAE,MAAO,EAAK,CAAC,CACzC,CACF,CAEA,eAAsB,EAAQ,EAAkB,EAAoC,CAClF,IAAM,EAAO,EAAU,EAAU,CAAQ,EACzC,GAAI,CACF,IAAM,EAAM,MAAA,EAAM,EAAA,SAAA,CAAS,EAAM,MAAM,EACjC,EAAQ,KAAK,MAAM,CAAG,EAC5B,OAAO,KAAK,IAAI,EAAI,EAAM,aAAe,EAAM,WAAa,GAC9D,MAAQ,CACN,MAAO,EACT,CACF,CAEA,eAAsB,EAAW,EAAiC,CAChE,GAAI,CACF,MAAA,EAAM,EAAA,GAAA,CAAG,EAAU,CAAE,UAAW,GAAM,MAAO,EAAK,CAAC,CACrD,MAAQ,CAER,CACF"}

package/dist/lib/cli/output.d.cts

@@ -0,0 +1,58 @@
+export declare const bold: (text: string) => string;
+export declare const dim: (text: string) => string;
+export declare const red: (text: string) => string;
+export declare const green: (text: string) => string;
+export declare const yellow: (text: string) => string;
+export declare const cyan: (text: string) => string;
+/** Enables quiet mode: only errors are printed. */
+export declare function setQuiet(value: boolean): void;
+/** Success message with a green check. */
+export declare function success(message: string): void;
+/** Indented info line with a cyan arrow. */
+export declare function info(message: string): void;
+/** Indented detail line (file lists, sub-items). */
+export declare function detail(message: string): void;
+/** Lifecycle event with a dim bracket tag, e.g. [dev], [change]. */
+export declare function event(tag: string, message: string): void;
+/** Warning; suppressed in quiet mode. */
+export declare function warn(message: string): void;
+/** Error; always printed, even in quiet mode. */
+export declare function error(message: string): void;
+/** Formats a byte count as "640 B", "1.5 kB", "2.3 MB". */
+export declare function formatBytes(bytes: number): string;
+/** Formats a duration as "45ms" or "1.23s". */
+export declare function formatDuration(ms: number): string;
+/** Build phase line: checkmark + label + dim duration. */
+export declare function phase(label: string, durationMs: number): void;
+export interface FileEntry {
+    path: string;
+    bytes: number;
+}
+/**
+ * Renders the generated-file list as aligned "path  size" rows (plain text,
+ * no color). With more than MAX_FILE_ROWS entries, shows the SHOWN_FILE_ROWS
+ * largest plus a "… and N more" line.
+ */
+export declare function fileRows(files: FileEntry[], max?: number, shown?: number): string[];
+/** Prints the generated-file list: dim paths, aligned sizes. */
+export declare function fileList(files: FileEntry[]): void;
+export interface ServerBannerOptions {
+    name: string;
+    version: string;
+    /** Command label, e.g. "dev" or "preview". */
+    command: string;
+    localUrl: string;
+    networkUrl?: string;
+}
+/**
+ * Plain-text lines of the server startup banner (Astro-style, no box):
+ *
+ *   elur-kit v2.4.10 dev server running at:
+ *     → Local:    http://localhost:3000/
+ *     → Network:  http://192.168.1.20:3000/
+ */
+export declare function serverBannerLines(options: ServerBannerOptions): string[];
+/** Prints the server startup banner with brand colors. */
+export declare function serverBanner(options: ServerBannerOptions): void;
+/** First external (LAN) IPv4 address, for the Network URL. */
+export declare function getNetworkAddress(): string | undefined;

package/dist/lib/cli/output.d.ts

@@ -0,0 +1,58 @@
+export declare const bold: (text: string) => string;
+export declare const dim: (text: string) => string;
+export declare const red: (text: string) => string;
+export declare const green: (text: string) => string;
+export declare const yellow: (text: string) => string;
+export declare const cyan: (text: string) => string;
+/** Enables quiet mode: only errors are printed. */
+export declare function setQuiet(value: boolean): void;
+/** Success message with a green check. */
+export declare function success(message: string): void;
+/** Indented info line with a cyan arrow. */
+export declare function info(message: string): void;
+/** Indented detail line (file lists, sub-items). */
+export declare function detail(message: string): void;
+/** Lifecycle event with a dim bracket tag, e.g. [dev], [change]. */
+export declare function event(tag: string, message: string): void;
+/** Warning; suppressed in quiet mode. */
+export declare function warn(message: string): void;
+/** Error; always printed, even in quiet mode. */
+export declare function error(message: string): void;
+/** Formats a byte count as "640 B", "1.5 kB", "2.3 MB". */
+export declare function formatBytes(bytes: number): string;
+/** Formats a duration as "45ms" or "1.23s". */
+export declare function formatDuration(ms: number): string;
+/** Build phase line: checkmark + label + dim duration. */
+export declare function phase(label: string, durationMs: number): void;
+export interface FileEntry {
+    path: string;
+    bytes: number;
+}
+/**
+ * Renders the generated-file list as aligned "path  size" rows (plain text,
+ * no color). With more than MAX_FILE_ROWS entries, shows the SHOWN_FILE_ROWS
+ * largest plus a "… and N more" line.
+ */
+export declare function fileRows(files: FileEntry[], max?: number, shown?: number): string[];
+/** Prints the generated-file list: dim paths, aligned sizes. */
+export declare function fileList(files: FileEntry[]): void;
+export interface ServerBannerOptions {
+    name: string;
+    version: string;
+    /** Command label, e.g. "dev" or "preview". */
+    command: string;
+    localUrl: string;
+    networkUrl?: string;
+}
+/**
+ * Plain-text lines of the server startup banner (Astro-style, no box):
+ *
+ *   elur-kit v2.4.10 dev server running at:
+ *     → Local:    http://localhost:3000/
+ *     → Network:  http://192.168.1.20:3000/
+ */
+export declare function serverBannerLines(options: ServerBannerOptions): string[];
+/** Prints the server startup banner with brand colors. */
+export declare function serverBanner(options: ServerBannerOptions): void;
+/** First external (LAN) IPv4 address, for the Network URL. */
+export declare function getNetworkAddress(): string | undefined;

package/dist/lib/cli/ports.d.cts

@@ -0,0 +1,20 @@
+import type { Server } from "node:http";
+/** Max ports tried after the requested one before giving up. */
+export declare const MAX_PORT_FALLBACK_TRIES = 20;
+/**
+ * Exit code used when no port in the fallback range is available. The dev
+ * supervisor treats it as fatal and does not restart the worker.
+ */
+export declare const PORT_UNAVAILABLE_EXIT_CODE = 78;
+export interface ListenFallbackOptions {
+    /** Max fallbacks after the requested port. Default: MAX_PORT_FALLBACK_TRIES. */
+    maxTries?: number;
+    /** Called when a busy port is skipped: (busyPort, nextPort). */
+    onFallback?: (busyPort: number, nextPort: number) => void;
+}
+/**
+ * Listens on host:port, falling back to the next port while the failure is
+ * EADDRINUSE. Resolves with the port actually bound. Rejects with the
+ * original error for non-port failures or when the range is exhausted.
+ */
+export declare function listenWithFallback(server: Server, host: string, port: number, options?: ListenFallbackOptions): Promise<number>;

package/dist/lib/cli/ports.d.ts

@@ -0,0 +1,20 @@
+import type { Server } from "node:http";
+/** Max ports tried after the requested one before giving up. */
+export declare const MAX_PORT_FALLBACK_TRIES = 20;
+/**
+ * Exit code used when no port in the fallback range is available. The dev
+ * supervisor treats it as fatal and does not restart the worker.
+ */
+export declare const PORT_UNAVAILABLE_EXIT_CODE = 78;
+export interface ListenFallbackOptions {
+    /** Max fallbacks after the requested port. Default: MAX_PORT_FALLBACK_TRIES. */
+    maxTries?: number;
+    /** Called when a busy port is skipped: (busyPort, nextPort). */
+    onFallback?: (busyPort: number, nextPort: number) => void;
+}
+/**
+ * Listens on host:port, falling back to the next port while the failure is
+ * EADDRINUSE. Resolves with the port actually bound. Rejects with the
+ * original error for non-port failures or when the range is exhausted.
+ */
+export declare function listenWithFallback(server: Server, host: string, port: number, options?: ListenFallbackOptions): Promise<number>;