@kitr/storage 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Platon Podkopov
+
+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

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @kitr/storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Storage.** Save small values in the browser or in cookies with types, and read the same cookies on the server.
+
+```sh
+pnpm kitr add storage
+```
+
+`kitr add` installs the package and wires it into your app: the provider in `kitrrc.ts`, its config file and its `AGENTS.md` section. Import it from `@kitr/storage`.
+
+Built on localStorage, cookies.
+
+Read the guide at https://kitr.dev/packages/storage.
+
+Part of [kitr](https://kitr.dev), the TypeScript framework where everything is an add-on. MIT licensed.

package/dist/devtools-BTqcJ52N.js

@@ -0,0 +1,143 @@
+import { getStorageDriver, listStorage, parseCookies, removeStorageKey, serializeCookie } from "./index.js";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+// src/devtools.tsx
+/** The Storage panel: localStorage, sessionStorage and cookies with edit and remove buttons. */
+function panels(ui) {
+	const { Button, Empty, preview, Row, Section, Toolbar } = ui;
+	function pretty(raw) {
+		if (raw === null) return "";
+		try {
+			return JSON.stringify(JSON.parse(raw), null, 2);
+		} catch {
+			return raw;
+		}
+	}
+	function writeCookie(key, value) {
+		document.cookie = serializeCookie(key, value);
+	}
+	function sources() {
+		const area = (name, title) => {
+			const rows = listStorage(name);
+			return {
+				title,
+				rows,
+				save: (key, value) => getStorageDriver(name)?.set(key, value),
+				remove: (key) => removeStorageKey(name, key),
+				clear: () => {
+					for (const { key } of rows) removeStorageKey(name, key);
+				}
+			};
+		};
+		const cookies = typeof document === "undefined" ? {} : parseCookies(document.cookie);
+		return [
+			area("local", "localStorage"),
+			area("session", "sessionStorage"),
+			{
+				title: "cookies",
+				rows: Object.entries(cookies).map(([key, raw]) => ({
+					key,
+					raw
+				})),
+				save: writeCookie,
+				remove: (key) => writeCookie(key, null),
+				clear: () => {
+					for (const key of Object.keys(cookies)) writeCookie(key, null);
+				}
+			}
+		];
+	}
+	function StoragePanel({ app }) {
+		const hub = app.container.use("devtools");
+		useSyncExternalStore(hub.subscribe, () => hub.version, () => 0);
+		const [, tick] = useState(0);
+		const refresh = useCallback(() => tick((n) => n + 1), []);
+		useEffect(() => {
+			window.addEventListener("storage", refresh);
+			return () => window.removeEventListener("storage", refresh);
+		}, [refresh]);
+		return /* @__PURE__ */ jsx("div", {
+			className: "kitr-dt-stack",
+			children: sources().map((source) => /* @__PURE__ */ jsx(Section, {
+				title: source.title,
+				count: source.rows.length,
+				children: source.rows.length === 0 ? /* @__PURE__ */ jsx(Empty, { children: "Empty" }) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Toolbar, { children: /* @__PURE__ */ jsx(Button, {
+					danger: true,
+					onClick: () => {
+						source.clear();
+						refresh();
+					},
+					children: "Clear"
+				}) }), source.rows.map((row) => /* @__PURE__ */ jsx(ValueRow, {
+					item: row,
+					onSave: (value) => {
+						source.save(row.key, value);
+						refresh();
+					},
+					onRemove: () => {
+						source.remove(row.key);
+						refresh();
+					}
+				}, row.key))] })
+			}, source.title))
+		});
+	}
+	function ValueRow({ item, onSave, onRemove }) {
+		const [draft, setDraft] = useState(() => pretty(item.raw));
+		useEffect(() => setDraft(pretty(item.raw)), [item.raw]);
+		return /* @__PURE__ */ jsxs(Row, {
+			head: /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+				className: "kitr-dt-label kitr-dt-key",
+				children: item.key
+			}), /* @__PURE__ */ jsx("span", {
+				className: "kitr-dt-preview",
+				children: preview(item.raw ?? "")
+			})] }),
+			children: [/* @__PURE__ */ jsx("textarea", {
+				className: "kitr-dt-input",
+				"aria-label": `Value of ${item.key}`,
+				rows: 4,
+				value: draft,
+				onChange: (e) => setDraft(e.target.value)
+			}), /* @__PURE__ */ jsxs(Toolbar, { children: [/* @__PURE__ */ jsx(Button, {
+				onClick: () => onSave(draft),
+				children: "Save"
+			}), /* @__PURE__ */ jsx(Button, {
+				danger: true,
+				onClick: onRemove,
+				children: "Remove"
+			})] })]
+		});
+	}
+	return [{
+		id: "storage",
+		label: "Storage",
+		group: "data",
+		badge: () => {
+			const total = listStorage("local").length + listStorage("session").length;
+			return total ? {
+				value: total,
+				tone: "muted"
+			} : null;
+		},
+		render: (app) => /* @__PURE__ */ jsx(StoragePanel, { app }),
+		actions: [{
+			id: "clear-local",
+			label: "Clear local",
+			hint: "localStorage",
+			danger: true,
+			run: () => {
+				for (const { key } of listStorage("local")) removeStorageKey("local", key);
+			}
+		}, {
+			id: "clear-session",
+			label: "Clear session",
+			hint: "sessionStorage",
+			danger: true,
+			run: () => {
+				for (const { key } of listStorage("session")) removeStorageKey("session", key);
+			}
+		}]
+	}];
+}
+export { panels };

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import { KitrApp, StandardSchemaV1 } from "@kitr/core";
+/** Options for `config/storage.ts`: a key prefix and cookie defaults. */
+export interface StorageConfig {
+  /** Prefix for every storage key and cookie name, e.g. `myapp:`. Default none. */
+  prefix?: string;
+  /** Defaults merged into every cookie. */
+  cookie?: Omit<CookieOptions, 'name'>;
+}
+/**
+ * What a platform supplies to back `defineStorage` items: Capacitor Preferences on mobile,
+ * the Tauri store or an Electron JSON file on desktop, Web Storage in the browser.
+ * Reads are synchronous from a cache `hydrate()` fills at boot; writes go through in the background.
+ */
+export interface StorageDriver {
+  /** Shown in the devtools log, e.g. `web:local` or `capacitor:preferences`. */
+  name: string;
+  /** Load every stored key into memory before the first render. */
+  hydrate?(): Promise<void>;
+  /** The raw string stored under `key`, or null. Must answer synchronously. */
+  get(key: string): string | null;
+  /** Store a raw string. May persist in the background. */
+  set(key: string, raw: string): void;
+  /** Delete one key. */
+  remove(key: string): void;
+  /** Every stored key, for the devtools panel. */
+  keys(): string[];
+  /** Changes made elsewhere (another tab, the native side). */
+  subscribe?(listener: (key: string | null) => void): () => void;
+}
+declare module '@kitr/core' {
+  interface ConfigRegistry {
+    storage: StorageConfig;
+  }
+  interface DriverTypes {
+    storage: StorageDriver;
+  }
+}
+/** Type-checks `config/storage.ts`. Returns the object unchanged. */
+export declare const defineConfig: <const C extends StorageConfig>(config: C) => C;
+/** Turns a value into the string that is stored and back. Pass one as `codec` to change the format. */
+export interface Codec<T> {
+  /** Value to stored string. */
+  encode(value: T): string;
+  /** Stored string to value. Throwing makes the item fall back to its default. */
+  decode(raw: string): T;
+}
+/** The default codec for objects: `JSON.stringify` and `JSON.parse`. */
+export declare const jsonCodec: <T>() => Codec<T>;
+/** Stores strings as they are, with no quotes. The default for cookies whose default is a string. */
+export declare const stringCodec: Codec<string>;
+/** `local` keeps a value until it is cleared; `session` keeps it for the current tab. */
+export type StorageArea = 'local' | 'session';
+/** Options for `defineStorage`: the default, the area, and how stored values are checked. */
+export interface StorageItemOptions<T> {
+  /** Returned when the key is missing, unparsable, invalid or on the server. */
+  default: T;
+  /** Where it is stored. Default `local`. */
+  area?: StorageArea;
+  /** Validate what comes back from storage (Standard Schema: zod, valibot...). Invalid → default. */
+  schema?: StandardSchemaV1<unknown, T>;
+  /** Format of the stored envelope. Default: JSON. */
+  codec?: Codec<T>;
+  /** Bump when the shape changes; stored values with another version are migrated or dropped. */
+  version?: number;
+  /** Converts a value stored under an older `version`. Without it, old values are dropped. */
+  migrate?: (raw: unknown, fromVersion: number) => T;
+  /** Keep this many ms, then treat as missing. Stored beside the value. */
+  ttl?: number;
+}
+/** A typed value in local or session storage, returned by `defineStorage`. */
+export interface StorageItem<T> {
+  /** The name it was defined with, without the config prefix. */
+  readonly key: string;
+  /** Which area it lives in. */
+  readonly area: StorageArea;
+  /** The stored value, or the default when it is missing, invalid, expired or on the server. */
+  get(): T;
+  /** Store a value, or compute it from the current one. A no-op on the server. */
+  set(value: T | ((current: T) => T)): void;
+  /** Delete the stored value so `get()` returns the default. */
+  remove(): void;
+  /** Fires on set/remove here and in other tabs (`storage` event). */
+  subscribe(listener: (value: T) => void): () => void;
+  /** The default, for server snapshots. */
+  readonly default: T;
+}
+/** Web Storage as a driver. Null outside a browser, so items fall back to their defaults. */
+export declare function createWebStorageDriver(name: StorageArea): StorageDriver | null;
+/** In-memory driver: tests, the server, and `session` items on native platforms. */
+export declare function createMemoryStorageDriver(name?: string): StorageDriver;
+/**
+ * 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.
+ */
+export declare function createAsyncStorageDriver(options: {
+  name: string;
+  load(): Promise<Record<string, string>>;
+  write(key: string, raw: string): Promise<void>;
+  erase(key: string): Promise<void>;
+  onError?: (error: unknown) => void;
+}): StorageDriver;
+/**
+ * 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.
+ */
+export declare function setStorageDriver(driver: StorageDriver, areas?: {
+  local?: StorageDriver;
+  session?: StorageDriver;
+}): void;
+/** The driver behind an area: the platform driver, Web Storage, or null on the server. */
+export declare function getStorageDriver(name: StorageArea): StorageDriver | null;
+/** Set by the provider from `config/storage.ts`; items created later pick it up. */
+export declare function setStoragePrefix(prefix: string): void;
+/**
+ * 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.
+ */
+export declare function defineStorage<T>(name: string, options: StorageItemOptions<T>): StorageItem<T>;
+/** Attributes written into `Set-Cookie`. `path: '/'` and `sameSite: 'lax'` apply unless overridden. */
+export interface CookieOptions {
+  /** URL path the cookie is sent for. */
+  path?: string;
+  /** Domain the cookie is sent to, e.g. `.acme.com` to share it with subdomains. */
+  domain?: string;
+  /** Seconds. */
+  maxAge?: number;
+  /** Absolute expiry date. */
+  expires?: Date;
+  /** Send only over HTTPS. Forced on when `sameSite` is `none`. */
+  secure?: boolean;
+  /** Server-set cookies only; the browser cannot write httpOnly cookies. */
+  httpOnly?: boolean;
+  /** Cross-site sending rule. */
+  sameSite?: 'lax' | 'strict' | 'none';
+}
+/** Options for `defineCookie`: the default, validation, format, and the cookie attributes. */
+export interface CookieItemOptions<T> extends CookieOptions {
+  /** Returned when the cookie is missing or invalid. */
+  default: T;
+  /** Validate the decoded value (Standard Schema). Invalid → default. */
+  schema?: StandardSchemaV1<unknown, T>;
+  /** Default: JSON for objects, plain string for string defaults. */
+  codec?: Codec<T>;
+}
+/** Anything that can hold cookies: a `Cookie` header string, a Headers object or `document`. */
+export type CookieSource = string | null | undefined | Headers | {
+  cookie?: string | null;
+};
+/** A typed cookie returned by `defineCookie`, readable on both sides. */
+export interface CookieItem<T> {
+  /** The name it was defined with, without the config prefix. */
+  readonly name: string;
+  /** Returned when the cookie is missing or invalid. */
+  readonly default: T;
+  /** The attributes given to `defineCookie`. */
+  readonly options: CookieOptions;
+  /** Read from `document.cookie`, or from the given source on the server. */
+  get(source?: CookieSource): T;
+  /** Write `document.cookie` (client). On the server use `cookies(event).set(item, value)`. */
+  set(value: T, options?: CookieOptions): void;
+  /** Expire the cookie in the browser. A no-op on the server. */
+  remove(): void;
+  /** Fires after `set`, `remove` or `notifyCookiesChanged()` in this tab. */
+  subscribe(listener: (value: T) => void): () => void;
+  /** The `Set-Cookie` header value for this item. */
+  serialize(value: T | null, options?: CookieOptions): string;
+  /** Parse one raw cookie value into T (or the default). */
+  decode(raw: string | undefined): T;
+}
+/** Attributes merged into every cookie this app writes. The provider sets them from `cookie` in config. */
+export declare function setCookieDefaults(defaults: Omit<CookieOptions, 'name'>): void;
+/** Parse a `Cookie` header into a map. Values are decoded with decodeURIComponent. */
+export declare function parseCookies(header: string | null | undefined): Record<string, string>;
+/** Build a `Set-Cookie` value. `value === null` expires the cookie. */
+export declare function serializeCookie(name: string, value: string | null, options?: CookieOptions): string;
+/**
+ * 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)
+ */
+export declare function defineCookie<T = string>(name: string, options: CookieItemOptions<T>): CookieItem<T>;
+/** Call after something else wrote `document.cookie` so `useCookie()` re-reads. */
+export declare function notifyCookiesChanged(): void;
+/** Every key in an area, for the devtools panel. */
+export declare function listStorage(name: StorageArea): Array<{
+  key: string;
+  raw: string | null;
+}>;
+/** Delete one raw key from an area and notify subscribers. Used by the devtools panel. */
+export declare function removeStorageKey(name: StorageArea, key: string): void;
+/** Write a line to the devtools `storage` channel. Does nothing when devtools are off. */
+export declare function logStorage(app: KitrApp, label: string, data?: unknown): void;