@kitr/storage 0.0.0-stage → 0.3.0

package/dist/index.js

@@ -0,0 +1,367 @@
+import { createDefineConfig, getDevtools, validateSync } from "@kitr/core";
+// src/index.ts
+/** Type-checks `config/storage.ts`. Returns the object unchanged. */
+const defineConfig = createDefineConfig();
+/** The default codec for objects: `JSON.stringify` and `JSON.parse`. */
+const jsonCodec = () => ({
+	encode: (v) => JSON.stringify(v),
+	decode: (raw) => JSON.parse(raw)
+});
+/** Stores strings as they are, with no quotes. The default for cookies whose default is a string. */
+const stringCodec = {
+	encode: (v) => v,
+	decode: (raw) => raw
+};
+const listenersByKey = /* @__PURE__ */ new Map();
+let crossTabInstalled = false;
+function webStorage(name) {
+	try {
+		if (typeof window === "undefined") return null;
+		const s = name === "local" ? window.localStorage : window.sessionStorage;
+		s.getItem("__kitr__");
+		return s;
+	} catch {
+		return null;
+	}
+}
+/** Web Storage as a driver. Null outside a browser, so items fall back to their defaults. */
+function createWebStorageDriver(name) {
+	const s = webStorage(name);
+	if (!s) return null;
+	return {
+		name: `web:${name}`,
+		get: (key) => s.getItem(key),
+		set: (key, raw) => s.setItem(key, raw),
+		remove: (key) => s.removeItem(key),
+		keys: () => {
+			const out = [];
+			for (let i = 0; i < s.length; i++) {
+				const key = s.key(i);
+				if (key !== null) out.push(key);
+			}
+			return out;
+		},
+		subscribe: (listener) => {
+			if (typeof window === "undefined") return () => {};
+			const handler = (e) => {
+				if (e.storageArea === s) listener(e.key);
+			};
+			window.addEventListener("storage", handler);
+			return () => window.removeEventListener("storage", handler);
+		}
+	};
+}
+/** In-memory driver: tests, the server, and `session` items on native platforms. */
+function createMemoryStorageDriver(name = "memory") {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		name,
+		get: (key) => map.get(key) ?? null,
+		set: (key, raw) => void map.set(key, raw),
+		remove: (key) => void map.delete(key),
+		keys: () => [...map.keys()]
+	};
+}
+/**
+* Build a driver over an async native store. `load` runs once at boot and fills the cache;
+* `write`/`erase` run in the background after each change, so reads stay synchronous.
+*/
+function createAsyncStorageDriver(options) {
+	const cache = /* @__PURE__ */ new Map();
+	const fail = options.onError ?? ((e) => console.error(`[@kitr/storage] ${options.name}:`, e));
+	return {
+		name: options.name,
+		async hydrate() {
+			try {
+				for (const [k, v] of Object.entries(await options.load())) cache.set(k, v);
+			} catch (e) {
+				fail(e);
+			}
+		},
+		get: (key) => cache.get(key) ?? null,
+		set: (key, raw) => {
+			cache.set(key, raw);
+			options.write(key, raw).catch(fail);
+		},
+		remove: (key) => {
+			cache.delete(key);
+			options.erase(key).catch(fail);
+		},
+		keys: () => [...cache.keys()]
+	};
+}
+const drivers = {};
+const driverUnsubscribers = [];
+/**
+* Replace the Web Storage backing with a platform driver. Called by the storage provider when a
+* platform registered one (`app.drivers.register('storage', driver)`); `session` items keep an
+* in-memory driver unless `areas` says otherwise.
+*/
+function setStorageDriver(driver, areas = {}) {
+	drivers.local = areas.local ?? driver;
+	drivers.session = areas.session ?? createMemoryStorageDriver("memory:session");
+	for (const stop of driverUnsubscribers.splice(0)) stop();
+	for (const d of [drivers.local, drivers.session]) {
+		const stop = d.subscribe?.((key) => {
+			if (key === null) for (const set of listenersByKey.values()) for (const l of set) l();
+			else emit(key);
+		});
+		if (stop) driverUnsubscribers.push(stop);
+	}
+}
+/** The driver behind an area: the platform driver, Web Storage, or null on the server. */
+function getStorageDriver(name) {
+	if (drivers[name] === void 0) drivers[name] = createWebStorageDriver(name);
+	return drivers[name] ?? null;
+}
+function area(name) {
+	return getStorageDriver(name);
+}
+function installCrossTab() {
+	if (crossTabInstalled || typeof window === "undefined") return;
+	crossTabInstalled = true;
+	window.addEventListener("storage", (e) => {
+		if (drivers.local && drivers.local.name !== "web:local") return;
+		if (!e.key) return;
+		for (const l of listenersByKey.get(e.key) ?? []) l();
+	});
+}
+function emit(key) {
+	for (const l of listenersByKey.get(key) ?? []) l();
+}
+let keyPrefix = "";
+/** Set by the provider from `config/storage.ts`; items created later pick it up. */
+function setStoragePrefix(prefix) {
+	keyPrefix = prefix;
+}
+/**
+* A typed item in localStorage or sessionStorage.
+*
+*   const sidebar = defineStorage('sidebar', { default: { open: true } })
+*   sidebar.get().open; sidebar.set((s) => ({ ...s, open: false }))
+*
+* Safe everywhere: on the server (or when storage is blocked) `get()` returns the default
+* and `set()` is a no-op, so the same module renders on both sides.
+*/
+function defineStorage(name, options) {
+	const areaName = options.area ?? "local";
+	const codec = options.codec ?? jsonCodec();
+	const version = options.version ?? 1;
+	const fullKey = () => `${keyPrefix}${name}`;
+	let cache;
+	const parse = (raw) => {
+		if (raw === null) return options.default;
+		try {
+			const env = codec.decode(raw);
+			if (!env || typeof env !== "object" || !("d" in env)) return options.default;
+			if (env.e !== void 0 && env.e < Date.now()) return options.default;
+			let data = env.d;
+			if (env.v !== version) {
+				if (!options.migrate) return options.default;
+				data = options.migrate(data, env.v);
+			}
+			if (options.schema) {
+				const result = validateSync(options.schema, data);
+				return result.success ? result.data : options.default;
+			}
+			return data;
+		} catch {
+			return options.default;
+		}
+	};
+	const item = {
+		key: name,
+		area: areaName,
+		default: options.default,
+		get() {
+			const s = area(areaName);
+			if (!s) return options.default;
+			const raw = s.get(fullKey());
+			if (cache && cache.raw === raw) return cache.value;
+			const value = parse(raw);
+			cache = {
+				raw,
+				value
+			};
+			return value;
+		},
+		set(next) {
+			const s = area(areaName);
+			if (!s) return;
+			const value = typeof next === "function" ? next(item.get()) : next;
+			const env = {
+				v: version,
+				d: value
+			};
+			if (options.ttl) env.e = Date.now() + options.ttl;
+			try {
+				s.set(fullKey(), codec.encode(env));
+			} catch {
+				cache = {
+					raw: null,
+					value
+				};
+			}
+			emit(fullKey());
+		},
+		remove() {
+			area(areaName)?.remove(fullKey());
+			cache = void 0;
+			emit(fullKey());
+		},
+		subscribe(listener) {
+			installCrossTab();
+			const key = fullKey();
+			const wrapped = () => listener(item.get());
+			let set = listenersByKey.get(key);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				listenersByKey.set(key, set);
+			}
+			set.add(wrapped);
+			return () => {
+				set.delete(wrapped);
+			};
+		}
+	};
+	return item;
+}
+const cookieListeners = /* @__PURE__ */ new Set();
+let cookieDefaults = {};
+/** Attributes merged into every cookie this app writes. The provider sets them from `cookie` in config. */
+function setCookieDefaults(defaults) {
+	cookieDefaults = defaults;
+}
+/** Parse a `Cookie` header into a map. Values are decoded with decodeURIComponent. */
+function parseCookies(header) {
+	const out = {};
+	if (!header) return out;
+	for (const part of header.split(";")) {
+		const i = part.indexOf("=");
+		if (i < 0) continue;
+		const k = part.slice(0, i).trim();
+		if (!k) continue;
+		const v = part.slice(i + 1).trim();
+		try {
+			out[k] = decodeURIComponent(v);
+		} catch {
+			out[k] = v;
+		}
+	}
+	return out;
+}
+/** Build a `Set-Cookie` value. `value === null` expires the cookie. */
+function serializeCookie(name, value, options = {}) {
+	const parts = [`${name}=${value === null ? "" : encodeURIComponent(value)}`];
+	const o = {
+		path: "/",
+		sameSite: "lax",
+		...cookieDefaults,
+		...options
+	};
+	if (value === null) parts.push("Max-Age=0", "Expires=Thu, 01 Jan 1970 00:00:00 GMT");
+	else {
+		if (o.maxAge !== void 0) parts.push(`Max-Age=${Math.floor(o.maxAge)}`);
+		if (o.expires) parts.push(`Expires=${o.expires.toUTCString()}`);
+	}
+	if (o.domain) parts.push(`Domain=${o.domain}`);
+	if (o.path) parts.push(`Path=${o.path}`);
+	if (o.secure || o.sameSite === "none") parts.push("Secure");
+	if (o.httpOnly) parts.push("HttpOnly");
+	if (o.sameSite) parts.push(`SameSite=${o.sameSite[0].toUpperCase()}${o.sameSite.slice(1)}`);
+	return parts.join("; ");
+}
+function headerFrom(source) {
+	if (source === void 0) return typeof document === "undefined" ? void 0 : document.cookie;
+	if (source === null || typeof source === "string") return source;
+	if (typeof Headers !== "undefined" && source instanceof Headers) return source.get("cookie");
+	return source.cookie;
+}
+/**
+* A typed cookie, readable on both sides and writable from the browser or the server.
+*
+*   const locale = defineCookie('locale', { default: 'en', maxAge: 60 * 60 * 24 * 365 })
+*   locale.get()                      // client: document.cookie
+*   locale.get(request.headers)       // server: any Headers / Cookie header string
+*   locale.set('de')                  // client
+*   cookies(event).set(locale, 'de')  // server (@kitr/storage/server)
+*/
+function defineCookie(name, options) {
+	const { default: fallback, schema, codec: givenCodec, ...cookieOptions } = options;
+	const codec = givenCodec ?? (typeof fallback === "string" ? stringCodec : jsonCodec());
+	const fullName = () => `${keyPrefix}${name}`;
+	const decode = (raw) => {
+		if (raw === void 0) return fallback;
+		try {
+			const data = codec.decode(raw);
+			if (schema) {
+				const result = validateSync(schema, data);
+				return result.success ? result.data : fallback;
+			}
+			return data;
+		} catch {
+			return fallback;
+		}
+	};
+	const item = {
+		name,
+		default: fallback,
+		options: cookieOptions,
+		decode,
+		get(source) {
+			const header = headerFrom(source);
+			if (header === void 0) return fallback;
+			return decode(parseCookies(header)[fullName()]);
+		},
+		serialize(value, overrides) {
+			return serializeCookie(fullName(), value === null ? null : codec.encode(value), {
+				...cookieOptions,
+				...overrides
+			});
+		},
+		set(value, overrides) {
+			if (typeof document === "undefined") return;
+			document.cookie = item.serialize(value, {
+				...overrides,
+				httpOnly: false
+			});
+			for (const l of cookieListeners) l();
+		},
+		remove() {
+			if (typeof document === "undefined") return;
+			document.cookie = item.serialize(null);
+			for (const l of cookieListeners) l();
+		},
+		subscribe(listener) {
+			const wrapped = () => listener(item.get());
+			cookieListeners.add(wrapped);
+			return () => {
+				cookieListeners.delete(wrapped);
+			};
+		}
+	};
+	return item;
+}
+/** Call after something else wrote `document.cookie` so `useCookie()` re-reads. */
+function notifyCookiesChanged() {
+	for (const l of cookieListeners) l();
+}
+/** Every key in an area, for the devtools panel. */
+function listStorage(name) {
+	const s = area(name);
+	if (!s) return [];
+	return s.keys().map((key) => ({
+		key,
+		raw: s.get(key)
+	}));
+}
+/** Delete one raw key from an area and notify subscribers. Used by the devtools panel. */
+function removeStorageKey(name, key) {
+	area(name)?.remove(key);
+	emit(key);
+}
+/** Write a line to the devtools `storage` channel. Does nothing when devtools are off. */
+function logStorage(app, label, data) {
+	getDevtools(app)?.log("storage", label, data);
+}
+export { createAsyncStorageDriver, createMemoryStorageDriver, createWebStorageDriver, defineConfig, defineCookie, defineStorage, getStorageDriver, jsonCodec, listStorage, logStorage, notifyCookiesChanged, parseCookies, removeStorageKey, serializeCookie, setCookieDefaults, setStorageDriver, setStoragePrefix, stringCodec };

package/dist/kitr.d.ts

@@ -0,0 +1,10 @@
+/** `kitr add storage`: typed localStorage/sessionStorage items and cookies with one API on the client and the server. */
+declare const _default: {
+  readonly name: "storage";
+  readonly add: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly remove: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly eject: {
+    readonly '@kitr/storage': "localStorage / document.cookie (+ a cookie parser)";
+  };
+};
+export { _default as default };

package/dist/kitr.js

@@ -0,0 +1,46 @@
+import { definePackage } from "@kitr/core/package";
+// src/kitr.ts
+/** `kitr add storage`: typed localStorage/sessionStorage items and cookies with one API on the client and the server. */
+var kitr_default = definePackage({
+	name: "storage",
+	add(ctx) {
+		const serverOnly = ctx.isServerOnly;
+		ctx.provider.add("@kitr/storage/provider");
+		ctx.config("storage", `import { defineConfig } from '@kitr/storage'
+
+export default defineConfig({
+  // Prefixes every storage key and cookie name so several apps on one origin never collide.
+  prefix: '${(ctx.pkg.name ?? "app").replace(/^@[^/]+\//, "").replace(/[^a-z0-9]+/gi, "-")}:',
+  cookie: { path: '/', sameSite: 'lax', secure: import.meta.env?.PROD ?? false },
+})
+`);
+		ctx.write("app/storage.ts", serverOnly ? `import { defineCookie } from '@kitr/storage'
+
+/** Cookies are typed once and read with \`cookies(event).get(item)\` from @kitr/storage/server. */
+export const localeCookie = defineCookie('locale', { default: 'en', maxAge: 60 * 60 * 24 * 365 })
+` : `import { defineCookie, defineStorage } from '@kitr/storage'
+
+/**
+ * Every persisted value, in one file, typed. Components read them with
+ * \`useStorage(item)\` / \`useCookie(item)\` from @kitr/storage/react; plain code with \`item.get()\`.
+ */
+export const sidebar = defineStorage('sidebar', { default: { collapsed: false } })
+
+export const recentSearches = defineStorage<string[]>('recent-searches', {
+  default: [],
+  area: 'session',
+  version: 1,
+})
+
+/** Readable on the server too (\`localeCookie.get(request.headers)\`), so SSR picks the right locale. */
+export const localeCookie = defineCookie('locale', { default: 'en', maxAge: 60 * 60 * 24 * 365 })
+`);
+		ctx.agents.add("storage", serverOnly ? `- Cookies: declare with \`defineCookie\` in \`app/storage.ts\`; in controllers use \`const jar = cookies(ctx.event)\` from \`@kitr/storage/server\`, then \`jar.get(item)\` / \`jar.set(item, value, { httpOnly: true })\`.` : `- Persisted values are declared once in \`app/storage.ts\` (\`defineStorage\` for local/session storage, \`defineCookie\` for cookies) and never read through \`localStorage\`/\`document.cookie\` directly.\n- Components: \`const [value, setValue] = useStorage(item)\` / \`useCookie(item)\` from \`@kitr/storage/react\`. Both are hydration-safe: the server and first render see the default.\n- Server side (actions, controllers): \`cookies(event).get(item)\` / \`.set(item, value)\` from \`@kitr/storage/server\`; wrap the root route in \`<CookieHeader value={request.headers.get('cookie')}>\` so \`useCookie\` renders the right value during SSR.\n- Add \`schema\` (zod/valibot) to validate what comes back from storage, \`version\` + \`migrate\` when a shape changes, \`ttl\` to expire.`);
+	},
+	remove(ctx) {
+		ctx.provider.remove("@kitr/storage/provider");
+		ctx.agents.remove("storage");
+	},
+	eject: { "@kitr/storage": "localStorage / document.cookie (+ a cookie parser)" }
+});
+export { kitr_default as default };

package/dist/provider.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Applies `config/storage.ts` (key prefix, cookie defaults), switches `defineStorage`
+ * items to the platform's native driver when one is registered, hydrates it before the first
+ * render, and contributes the Storage panel to the devtools.
+ */
+export declare const storageProvider: import("@kitr/core").KitrProvider;
+export { storageProvider as default };

package/dist/provider.js

@@ -0,0 +1,29 @@
+import { getStorageDriver, setCookieDefaults, setStorageDriver, setStoragePrefix } from "./index.js";
+import { defineProvider, getDevtools } from "@kitr/core";
+// src/provider.ts
+/**
+* Applies `config/storage.ts` (key prefix, cookie defaults), switches `defineStorage`
+* items to the platform's native driver when one is registered, hydrates it before the first
+* render, and contributes the Storage panel to the devtools.
+*/
+const storageProvider = defineProvider({
+	name: "storage",
+	register(app) {
+		const config = app.config.get("storage", {});
+		if (config.prefix) setStoragePrefix(config.prefix);
+		if (config.cookie) setCookieDefaults(config.cookie);
+		const driver = app.drivers.resolve("storage");
+		if (driver) setStorageDriver(driver);
+	},
+	async boot(app) {
+		const driver = app.drivers.resolve("storage");
+		if (driver && getStorageDriver("local") !== driver) setStorageDriver(driver);
+		await driver?.hydrate?.();
+		const hub = getDevtools(app);
+		if (!hub) return;
+		hub.log("storage", `driver: ${getStorageDriver("local")?.name ?? "none (server)"}`);
+		for (const area of ["local", "session"]) getStorageDriver(area)?.subscribe?.((key) => hub.log("storage", `${key ?? "storage"} changed outside this context`));
+	},
+	devtools: typeof __KITR_DEVTOOLS__ === "boolean" && __KITR_DEVTOOLS__ === false ? void 0 : (_app, ui) => import("./devtools-BTqcJ52N.js").then((m) => m.panels(ui))
+});
+export { storageProvider as default, storageProvider };

package/dist/react.d.ts

@@ -0,0 +1,20 @@
+import { CookieItem, StorageItem } from "./index.js";
+import { ReactNode } from "react";
+/**
+ * Gives `useCookie()` the request's `Cookie` header during server rendering, so the first
+ * HTML shows the stored value instead of the default. Wrap the tree once, in the root route.
+ */
+export declare function CookieHeader({ value, children }: {
+  value: string | null | undefined;
+  children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<string | null | undefined>>;
+/**
+ * Read and write a storage item from a component. Hydration-safe: the server (and the first
+ * client render) see the default, then the stored value applies, so markup always matches.
+ */
+export declare function useStorage<T>(item: StorageItem<T>): [T, (value: T | ((current: T) => T)) => void, () => void];
+/**
+ * Read and write a cookie from a component. On the server the value comes from
+ * `<CookieHeader>` when present, otherwise the default.
+ */
+export declare function useCookie<T>(item: CookieItem<T>): [T, (value: T) => void, () => void];

package/dist/react.js

@@ -0,0 +1,40 @@
+import { createContext, createElement, useCallback, useContext, useSyncExternalStore } from "react";
+// src/react.ts
+/**
+* The request's `Cookie` header during server rendering, so `useCookie()` renders the
+* same value the browser will hydrate with. Wrap the tree once, in the root route:
+*
+*   <CookieHeader value={request.headers.get('cookie')}>...</CookieHeader>
+*/
+const CookieHeaderContext = createContext(void 0);
+/**
+* Gives `useCookie()` the request's `Cookie` header during server rendering, so the first
+* HTML shows the stored value instead of the default. Wrap the tree once, in the root route.
+*/
+function CookieHeader({ value, children }) {
+	return createElement(CookieHeaderContext.Provider, { value }, children);
+}
+/**
+* Read and write a storage item from a component. Hydration-safe: the server (and the first
+* client render) see the default, then the stored value applies, so markup always matches.
+*/
+function useStorage(item) {
+	return [
+		useSyncExternalStore(useCallback((onChange) => item.subscribe(onChange), [item]), () => item.get(), () => item.default),
+		item.set,
+		item.remove
+	];
+}
+/**
+* Read and write a cookie from a component. On the server the value comes from
+* `<CookieHeader>` when present, otherwise the default.
+*/
+function useCookie(item) {
+	const header = useContext(CookieHeaderContext);
+	return [
+		useSyncExternalStore(useCallback((onChange) => item.subscribe(onChange), [item]), () => item.get(), () => item.get(header ?? null)),
+		item.set,
+		item.remove
+	];
+}
+export { CookieHeader, useCookie, useStorage };

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+import { CookieItem, CookieOptions } from "./index.js";
+/** The parts of an h3 v2 event (or anything request/response shaped) that cookies need. */
+export interface CookieEventLike {
+  /** The request; only its headers are read. */
+  req: {
+    headers: Headers;
+  };
+  /** The response; `Set-Cookie` headers are appended here. */
+  res: {
+    headers: Headers;
+  };
+}
+/** Typed cookie access for one request, returned by `cookies()`. */
+export interface ServerCookies {
+  /** The item's value from the request's `Cookie` header, or its default. */
+  get<T>(item: CookieItem<T>): T;
+  /** Appends a `Set-Cookie` header; `httpOnly` and the other item options apply. */
+  set<T>(item: CookieItem<T>, value: T, options?: CookieOptions): void;
+  /** Appends a `Set-Cookie` header that expires the cookie. */
+  remove(item: CookieItem<unknown>): void;
+  /** The raw `Cookie` header, for `<CookieHeader>` during SSR. */
+  readonly header: string | null;
+}
+/**
+ * Typed cookies on the server: `cookies(event)` in a controller or middleware,
+ * `cookies(request, responseHeaders)` anywhere you only have the Fetch primitives.
+ */
+export declare function cookies(event: CookieEventLike): ServerCookies;
+export declare function cookies(request: Request, responseHeaders: Headers): ServerCookies;

package/dist/server.js

@@ -0,0 +1,14 @@
+// src/server.ts
+function cookies(source, responseHeaders) {
+	const reqHeaders = "req" in source ? source.req.headers : source.headers;
+	const resHeaders = "res" in source ? source.res.headers : responseHeaders;
+	const header = reqHeaders.get("cookie");
+	const headerSource = header;
+	return {
+		header,
+		get: (item) => item.get(headerSource),
+		set: (item, value, options) => resHeaders.append("set-cookie", item.serialize(value, options)),
+		remove: (item) => resHeaders.append("set-cookie", item.serialize(null))
+	};
+}
+export { cookies };