@plitzi/sdk-server 0.38.4 → 0.38.5

package/dist/core/server/pageServer.js

@@ -9,10 +9,12 @@ import { buildCacheManager } from "../../helpers/cache/cacheManager.js";
 import { createServerCaches, destroyServerCaches } from "../../helpers/cache/serverCaches.js";
 import normalizePlugins, { normalizePluginSource } from "../../helpers/normalizePlugins.js";
 import { reportReactBuild } from "../../helpers/reportReactBuild.js";
+import { isFunctionsDefinition } from "../../modules/functions/load.js";
 import { invalidatePluginComponentCache } from "../../modules/ssr/loadPluginComponents.js";
 import { DRAFT_STORE_METHODS, createMemoryDraftStore } from "../../modules/ssr/preview.js";
 import { compileTemplate } from "../../modules/ssr/template.js";
 import { PluginManager } from "../../plugins/manager.js";
+import { watchPluginSources } from "../../plugins/watch.js";
 import { makeHandler } from "../http/dispatcher.js";
 import { createDevReload } from "../http/stages/devReload.js";
 import { buildPagePipeline } from "../services/registry.js";
@@ -51,6 +53,17 @@ var createPageServer = (config, services, extensions) => {
 	const actions = actionsModuleFor(config);
 	const realtime = realtimeModuleFor(config);
 	const devReload = config.devReload ? createDevReload() : void 0;
+	/**
+	* A plugin whose source changed is built again and handed to the open pages, which swap it where it is drawn — the
+	* rest of the page, its state included, stays as it was. Only while developing with `devReload` on: nobody edits a
+	* deployment's plugins under it, and a page that does not listen has nothing to swap.
+	*/
+	const stopWatchingPlugins = devReload && config.devMode ? watchPluginSources(pluginManager, (key) => {
+		invalidatePluginComponentCache();
+		pluginManager.rebuild(key).then((entry) => {
+			if (entry?.js) devReload.plugin(entry);
+		});
+	}) : void 0;
 	const stages = [...devReload ? [devReload.stage] : [], ...buildPagePipeline(services, extensions)];
 	const makeHandlerForPort = (port) => {
 		const buildContext = (raw, rawRes, req, res) => ({
@@ -85,9 +98,14 @@ var createPageServer = (config, services, extensions) => {
 		},
 		onClosing: () => {
 			realtime?.close();
+			stopWatchingPlugins?.();
 			devReload?.close();
 		},
 		...devReload ? { reloadPages: devReload.reload } : {},
+		...actions ? { setPluginFunctions: (plugin, definition) => {
+			if (definition !== void 0 && !isFunctionsDefinition(definition)) throw new Error(`[SSR] The functions of plugin "${plugin}" are not a definition: defineFunctions({ … })`);
+			actions.setPluginFunctions(plugin, definition);
+		} } : {},
 		onDestroy: async () => {
 			await actions?.jobs?.stop();
 			destroyServerCaches(caches);

package/dist/core/services/registry.js

@@ -2,6 +2,7 @@ import { actionStage } from "./action.js";
 import { functionRoutesStage } from "./functionRoutes.js";
 import { realtimeStage } from "./realtime.js";
 import { rscStage } from "./rsc.js";
+import { spaceDocumentStage } from "./spaceDocument.js";
 import { imagesStage } from "../http/stages/images.js";
 import { notFoundStage, ssrStage } from "./ssr.js";
 import { authRoutesStages } from "../http/stages/authRoutes.js";
@@ -30,6 +31,7 @@ var buildPagePipeline = (services, extensions = {}) => {
 	stages.push(realtimeStage);
 	stages.push(...extensions.data ?? []);
 	stages.push(functionRoutesStage);
+	if (services.ssr) stages.push(spaceDocumentStage);
 	stages.push(services.ssr ? ssrStage : notFoundStage);
 	return stages;
 };

package/dist/core/services/rsc.js

@@ -6,7 +6,7 @@ var rscStage = async (ctx) => {
 	const rscPath = resolveRscEndpoint(config);
 	if (!rscPath || req.method !== "GET" || req.path !== rscPath) return false;
 	ctx.operation = "rsc";
-	await handleRsc(req, ctx.res, config, ctx.pluginManager, ctx.caches.rsc);
+	await handleRsc(req, ctx.res, config, ctx.pluginManager, ctx.caches.rsc, ctx.signal);
 	return true;
 };
 //#endregion

package/dist/core/services/spaceDocument.d.ts

@@ -0,0 +1,2 @@
+import { SSRContext, Stage } from '../http/types';
+export declare const spaceDocumentStage: Stage<SSRContext>;

package/dist/core/services/spaceDocument.js

@@ -0,0 +1,11 @@
+import { handleSpaceDocument } from "../../modules/ssr/spaceDocument.js";
+//#region src/core/services/spaceDocument.ts
+var spaceDocumentStage = async (ctx) => {
+	const { config, req } = ctx;
+	if (req.method !== "GET" || !req.path.startsWith("/_plitzi/space/")) return false;
+	ctx.operation = "space";
+	await handleSpaceDocument(req, ctx.res, config, ctx.caches.offlineData);
+	return true;
+};
+//#endregion
+export { spaceDocumentStage };

package/dist/functions-api.d.ts

@@ -200,6 +200,11 @@ declare type InteractionCallbackParam<T extends Record<string, unknown> = Record
 } & ({
     type: 'text';
     defaultValue?: string | number;
+}
+/** Written as text — a number or a template — and handed to the callback as a number. */
+| {
+    type: 'number';
+    defaultValue?: number;
 } | {
     type: 'textarea';
     defaultValue?: string | number;
@@ -244,7 +249,7 @@ declare type InteractionCallbackParam<T extends Record<string, unknown> = Record
 
 declare type InteractionCallbackParamValues<T extends Record<string, unknown> = Record<string, unknown>> = T;
 
-declare type InteractionParamType = 'boolean' | 'select' | 'text' | 'textarea' | 'codemirror-text' | 'codemirror-json' | 'elements';
+declare type InteractionParamType = 'boolean' | 'select' | 'text' | 'number' | 'textarea' | 'codemirror-text' | 'codemirror-json' | 'elements';
 
 /**
  * The lifetime a change writes with: a number of seconds, one worked out from the value written, or none.

package/dist/functionsRunner.d.ts

@@ -3,6 +3,9 @@
  * and the isolates both are made of. Its own entry, apart from the contract, so a space's code and a self-hosted
  * server's native functions never load a line of it — nor need `isolated-vm` or `core-js`, which only the process
  * that runs isolates installs.
+ *
+ * `buildFunctions` is the build every runner runs first, on its own: what `plitzi doctor` checks a project's
+ * `src/functions/` with, by the rules of the sdk-server the project installed.
  */
 export { startFunctionsRunnerService } from './modules/functions/runner/service';
 export type { FunctionsRunnerService, FunctionsRunnerServiceOptions } from './modules/functions/runner/service';
@@ -13,3 +16,5 @@ export type { IsolateRunnerOptions } from './modules/functions/sandbox/isolate';
 export { FUNCTIONS_PROTOCOL, FunctionFailure } from './modules/functions/protocol';
 export { createLocalFunctions } from './modules/functions/local';
 export type { LocalFunctions, LocalFunctionsOptions } from './modules/functions/local';
+export { buildFunctions, FunctionsBuildError } from './modules/functions/build';
+export type { FunctionsBuild, FunctionsSource } from './modules/functions/build';

package/dist/functionsRunner.js

@@ -1,6 +1,7 @@
 import { FUNCTIONS_PROTOCOL, FunctionFailure } from "./modules/functions/protocol.js";
+import { FunctionsBuildError, buildFunctions } from "./modules/functions/build.js";
 import { createIsolateRunner } from "./modules/functions/sandbox/isolate.js";
 import { startFunctionsRunnerService } from "./modules/functions/runner/service.js";
 import { createRemoteRunner } from "./modules/functions/runner/remote.js";
 import { createLocalFunctions } from "./modules/functions/local.js";
-export { FUNCTIONS_PROTOCOL, FunctionFailure, createIsolateRunner, createLocalFunctions, createRemoteRunner, startFunctionsRunnerService };
+export { FUNCTIONS_PROTOCOL, FunctionFailure, FunctionsBuildError, buildFunctions, createIsolateRunner, createLocalFunctions, createRemoteRunner, startFunctionsRunnerService };

package/dist/helpers/hydrationPayload.d.ts

@@ -1,11 +1,32 @@
 import { OfflineDataRaw } from '@plitzi/sdk-shared';
+/** The space as a page reads it, and the name of exactly that text. */
+export type SpaceDocument = {
+    json: string;
+    hash: string;
+};
+/**
+ * The space as the page reads it — escaped JSON, safe inside a `<script>` — made once per space object rather than
+ * once per render.
+ *
+ * It is most of the payload, and the adapters hand every request the same object until the space changes, so turning
+ * it into JSON on each render was a tenth of a render's CPU spent producing the same string. Keyed weakly: a space the
+ * adapters let go of takes its string with it.
+ *
+ * The compiled stylesheet is left out when the page's own runtime stylesheet carries it in a form the browser reads
+ * back exactly (`styleCacheTravelsInDocument`): it is the largest part of the style document, and the page would
+ * otherwise ship it twice. A fact of the space alone, so the document is the same wherever it is asked for.
+ *
+ * The hash names the text, so a page can be told where to fetch it and the answer can be kept forever.
+ */
+export declare const spaceDocument: (offlineData: OfflineDataRaw) => SpaceDocument;
 /**
  * What the page's bootstrap reads: `{ offlineData, ...rest }` as escaped JSON, byte for byte what serializing the
  * whole object would give. The escaping replaces characters one by one, so escaping the parts and joining them is
  * the same as escaping the whole.
  *
- * The compiled stylesheet is left out when the page's own runtime stylesheet carries it in a form the browser reads
- * back exactly (`styleCacheTravelsInDocument`), and `styleCacheInDocument` tells the bootstrap to. It is the largest
- * part of the style document, and the page would otherwise ship it twice.
+ * `apart`, the space is not in it: the page fetches it (`spaceDocumentPath`), and only what is this request's travels
+ * inline. `styleCacheInDocument` tells the bootstrap the stylesheet is in the page either way.
  */
-export declare const hydrationPayload: (offlineData: OfflineDataRaw | undefined, rest: Record<string, unknown>) => string;
+export declare const hydrationPayload: (offlineData: OfflineDataRaw | undefined, rest: Record<string, unknown>, { apart }?: {
+    apart?: boolean;
+}) => string;

package/dist/helpers/hydrationPayload.js

@@ -1,51 +1,57 @@
 import { escapeJson } from "./escapeJson.js";
+import { createHash } from "node:crypto";
 import { styleCacheTravelsInDocument } from "@plitzi/sdk-shared/style";
 //#region src/helpers/hydrationPayload.ts
-var serializedSpaces = /* @__PURE__ */ new WeakMap();
+var documents = /* @__PURE__ */ new WeakMap();
 /**
-* The space as the page embeds it, serialized once per space object rather than once per render.
+* The space as the page reads it — escaped JSON, safe inside a `<script>` — made once per space object rather than
+* once per render.
 *
-* It is most of the payload — tens of kilobytes of schema and style — and the adapters hand every request the same
-* object until the space changes, so turning it into escaped JSON on each render was a tenth of a render's CPU spent
-* producing the same string. Keyed weakly: a space the adapters let go of takes its string with it.
+* It is most of the payload, and the adapters hand every request the same object until the space changes, so turning
+* it into JSON on each render was a tenth of a render's CPU spent producing the same string. Keyed weakly: a space the
+* adapters let go of takes its string with it.
+*
+* The compiled stylesheet is left out when the page's own runtime stylesheet carries it in a form the browser reads
+* back exactly (`styleCacheTravelsInDocument`): it is the largest part of the style document, and the page would
+* otherwise ship it twice. A fact of the space alone, so the document is the same wherever it is asked for.
+*
+* The hash names the text, so a page can be told where to fetch it and the answer can be kept forever.
 */
-var serializeSpace = (offlineData, withoutStyleCache) => {
-	let serialized = serializedSpaces.get(offlineData);
-	if (!serialized) {
-		serialized = {};
-		serializedSpaces.set(offlineData, serialized);
-	}
-	if (withoutStyleCache) {
-		serialized.withoutStyleCache ??= escapeJson(JSON.stringify({
-			...offlineData,
-			style: {
-				...offlineData.style,
-				cache: ""
-			}
-		}));
-		return serialized.withoutStyleCache;
-	}
-	serialized.whole ??= escapeJson(JSON.stringify(offlineData));
-	return serialized.whole;
+var spaceDocument = (offlineData) => {
+	const known = documents.get(offlineData);
+	if (known) return known;
+	const space = styleCacheTravelsInDocument(offlineData.style.cache) ? {
+		...offlineData,
+		style: {
+			...offlineData.style,
+			cache: ""
+		}
+	} : offlineData;
+	const json = escapeJson(JSON.stringify(space));
+	const document = {
+		json,
+		hash: createHash("sha256").update(json).digest("base64url").slice(0, 22)
+	};
+	documents.set(offlineData, document);
+	return document;
 };
 /**
 * What the page's bootstrap reads: `{ offlineData, ...rest }` as escaped JSON, byte for byte what serializing the
 * whole object would give. The escaping replaces characters one by one, so escaping the parts and joining them is
 * the same as escaping the whole.
 *
-* The compiled stylesheet is left out when the page's own runtime stylesheet carries it in a form the browser reads
-* back exactly (`styleCacheTravelsInDocument`), and `styleCacheInDocument` tells the bootstrap to. It is the largest
-* part of the style document, and the page would otherwise ship it twice.
+* `apart`, the space is not in it: the page fetches it (`spaceDocumentPath`), and only what is this request's travels
+* inline. `styleCacheInDocument` tells the bootstrap the stylesheet is in the page either way.
 */
-var hydrationPayload = (offlineData, rest) => {
+var hydrationPayload = (offlineData, rest, { apart = false } = {}) => {
 	const inDocument = offlineData !== void 0 && styleCacheTravelsInDocument(offlineData.style.cache);
 	const serializedRest = escapeJson(JSON.stringify(inDocument ? {
 		...rest,
 		styleCacheInDocument: true
 	} : rest));
-	if (offlineData === void 0) return serializedRest;
+	if (offlineData === void 0 || apart) return serializedRest;
 	const separator = serializedRest === "{}" ? "" : ",";
-	return `{"offlineData":${serializeSpace(offlineData, inDocument)}${separator}${serializedRest.slice(1)}`;
+	return `{"offlineData":${spaceDocument(offlineData).json}${separator}${serializedRest.slice(1)}`;
 };
 //#endregion
-export { hydrationPayload };
+export { hydrationPayload, spaceDocument };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { createServer, resolveServices } from './core/createServer';
 export { closeOnSignals } from './core/server/closeOnSignals';
-export { loadFunctions, readFunctionsDir } from './modules/functions/load';
+export { loadFunctions, loadFunctionsSource, readFunctionsDir } from './modules/functions/load';
 export { freePort } from './core/freePort';
 export { registerHealthCheck, buildHealthPayload } from './core/health';
 export { consoleLogger, isLogged, logLevelOf, renderLogEvent, serverLog } from './helpers/serverLog';
@@ -25,6 +25,6 @@ export type { ConnectorAuth, ConnectorCredential, ConnectorEndpoints, ConnectorF
 export type { FontStore, StoredFont } from './core/fontStore';
 export type { PubSubAdapter, SSRRealtimeConfig } from '@plitzi/sdk-shared';
 export type { RedisPubSubClients } from './modules/realtime/redisPubSub';
-export type { ResolvedServices } from './core/createServer';
+export type { ResolvedServices, ServerConfig } from './core/createServer';
 export type { Closable, CloseOnSignalsOptions } from './core/server/closeOnSignals';
 export type { BaseContext, PipelineExtensions, SSRContext, Stage } from './core/http/types';

package/dist/index.js

@@ -3,13 +3,13 @@ import { fetchConnectorRecords, rebaseMedia, writeConnectorRecord } from "./modu
 import { createMemoryPubSub } from "./modules/realtime/memoryPubSub.js";
 import { createConnectorResolver } from "./modules/connectors/resolver.js";
 import { resolveRscData } from "./modules/rsc/resolveRscData.js";
+import { loadFunctions, loadFunctionsSource, readFunctionsDir } from "./modules/functions/load.js";
 import { PREVIEW_TOKEN_PARAM } from "./core/previewToken.js";
 import { createMemoryDraftStore, takeDraftOverride } from "./modules/ssr/preview.js";
 import { resolveServices } from "./core/services/resolve.js";
 import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
 import { createServer } from "./core/createServer.js";
 import { closeOnSignals } from "./core/server/closeOnSignals.js";
-import { loadFunctions, readFunctionsDir } from "./modules/functions/load.js";
 import { freePort } from "./core/freePort.js";
 import { createCloudAdapters } from "./adapters/cloudAdapters.js";
 import { createJsonAdapters } from "./adapters/jsonAdapters.js";
@@ -19,4 +19,4 @@ import { authoringPreview, fixedSpace, presentsCredential, verifiedDomain, wildc
 import { createSpaceAdapters } from "./adapters/space/index.js";
 import { createLocalFontStore, hostedPathsOf } from "./core/fontStore.js";
 import { createRedisPubSub } from "./modules/realtime/redisPubSub.js";
-export { PREVIEW_TOKEN_PARAM, authoringPreview, buildHealthPayload, closeOnSignals, consoleLogger, createAuthAdapters, createCloudAdapters, createConnectorResolver, createJsonAdapters, createLocalFontStore, createMemoryCache, createMemoryDraftStore, createMemoryPubSub, createRedisPubSub, createServer, createSpaceAdapters, fetchConnectorRecords, fixedSpace, freePort, hostedPathsOf, isLogged, loadFunctions, logLevelOf, presentsCredential, readFunctionsDir, rebaseMedia, refuse, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, serverLog, takeDraftOverride, verifiedDomain, wildcardSubdomain, writeConnectorRecord };
+export { PREVIEW_TOKEN_PARAM, authoringPreview, buildHealthPayload, closeOnSignals, consoleLogger, createAuthAdapters, createCloudAdapters, createConnectorResolver, createJsonAdapters, createLocalFontStore, createMemoryCache, createMemoryDraftStore, createMemoryPubSub, createRedisPubSub, createServer, createSpaceAdapters, fetchConnectorRecords, fixedSpace, freePort, hostedPathsOf, isLogged, loadFunctions, loadFunctionsSource, logLevelOf, presentsCredential, readFunctionsDir, rebaseMedia, refuse, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, serverLog, takeDraftOverride, verifiedDomain, wildcardSubdomain, writeConnectorRecord };

package/dist/modules/actions/index.d.ts

@@ -3,8 +3,10 @@ import { RunGuards } from './runtime/guards';
 import { ActionRunner } from './runtime/runAction';
 import { ActionKvStore, ActionsConfig, ActionTaskRegistry, ResolvedActionLimits, SpaceRevision } from './types';
 import { FunctionsSource } from '../functions/build';
+import { FunctionsDefinition } from '../functions/contract';
 import { ManifestReading } from '../functions/manifest';
 import { RouteHandler, RouteVisit } from '../functions/routes';
+import { FunctionScope } from '../functions/scope';
 import { PreparedFunctions } from '../functions/space';
 import { ActionDocument } from '@plitzi/sdk-shared';
 export type ActionsModule = ActionRunner & {
@@ -17,9 +19,10 @@ export type ActionsModule = ActionRunner & {
     registryFor: (spaceId: number, at?: SpaceRevision) => Promise<ActionTaskRegistry>;
     /**
      * A space's functions source, built, read and checked — ready to store, or the problems to show where they are. The
-     * one way a space's functions become storable; refused when this server has no runner.
+     * one way a space's functions become storable; refused when this server has no runner. With a `scope`, a plugin's
+     * server half: its tasks named after the plugin, its routes its own.
      */
-    prepareFunctions: (source: FunctionsSource) => Promise<PreparedFunctions>;
+    prepareFunctions: (source: FunctionsSource, scope?: FunctionScope) => Promise<PreparedFunctions>;
     /**
      * What a space's code declares, read by every rule a saved space's functions meet — for code that is not built here:
      * a space runtime's, described by the runtime itself when it starts. The manifest, and the problems that refuse it.
@@ -36,6 +39,12 @@ export type ActionsModule = ActionRunner & {
     kv: (spaceId: number) => ActionKvStore;
     /** What this server will allow one run of that document to spend — the deployment's ceilings, tightened by it. */
     limitsFor: (document: ActionDocument) => ResolvedActionLimits;
+    /**
+     * Puts the server half of a plugin this server ships in place — or takes it away, with none — while it runs: what a
+     * development server does when a plugin's `functions/` change, instead of restarting. Checked as at boot: a task not
+     * named after the plugin throws, and nothing changes.
+     */
+    setPluginFunctions: (plugin: string, definition: FunctionsDefinition | undefined) => void;
     /**
      * Scheduled runs: the queue, the sweep that fills it and the workers that drain it.
      *

package/dist/modules/actions/index.js

@@ -47,15 +47,29 @@ var withFleetKv = (config) => {
 };
 var createActionsModule = (given) => {
 	const config = withFleetKv(given);
-	const registry = createTaskRegistry(config.functions?.native, { db: (config.dbDrivers?.length ?? 0) > 0 });
+	const plugins = new Map(Object.entries(config.functions?.plugins ?? {}));
+	const build = (from) => createTaskRegistry(config.functions?.native, {
+		db: (config.dbDrivers?.length ?? 0) > 0,
+		plugins: Object.fromEntries(from)
+	});
+	let current = build(plugins);
+	const registry = {
+		get: (name) => current.get(name),
+		list: () => current.list()
+	};
 	const spaceRegistries = createSpaceRegistries(registry, config.functions);
-	const reserved = new Set(registry.list().map((task) => task.namespace));
-	const registryFor = async (spaceId, at) => spaceRegistries.registryFor(await config.lookups.getFunctions?.(spaceId, at));
+	const reserved = () => new Set(current.list().map((task) => task.namespace));
+	const registryFor = async (spaceId, at) => {
+		const [functions, plugins] = await Promise.all([config.lookups.getFunctions?.(spaceId, at), config.lookups.getPluginFunctions?.(spaceId, at)]);
+		return spaceRegistries.registryFor(functions, plugins);
+	};
 	const registryForRun = (request) => Object.values(request.entry.document.nodes).every((node) => node.type !== "task" || !node.action || registry.get(node.action)) ? registry : registryFor(request.spaceId, request.at);
 	const { runAction, taskContext } = createActionRunner(config, registryForRun, config.fetchImpl);
 	const routes = createRoutes({
 		config: config.functions ?? {},
+		plugins: () => plugins,
 		...config.lookups.getFunctions ? { getFunctions: config.lookups.getFunctions } : {},
+		...config.lookups.getPluginFunctions ? { getPluginFunctions: config.lookups.getPluginFunctions } : {},
 		taskContext
 	});
 	/**
@@ -71,17 +85,25 @@ var createActionsModule = (given) => {
 		registry,
 		registryFor,
 		routeFor: routes.routeFor,
-		prepareFunctions: (source) => {
+		prepareFunctions: (source, scope) => {
 			const runner = config.functions?.runner;
-			return runner ? prepareFunctions(source, runner, reserved, functionCeilings(config.functions?.limits)) : Promise.resolve({
+			return runner ? prepareFunctions(source, runner, reserved(), functionCeilings(config.functions?.limits), scope) : Promise.resolve({
 				ok: false,
 				problems: [{ message: "This server runs no space functions" }]
 			});
 		},
-		readManifest: (declared) => readManifest(declared, reserved, functionCeilings(config.functions?.limits)),
+		readManifest: (declared) => readManifest(declared, reserved(), functionCeilings(config.functions?.limits)),
 		guards,
 		kv: (spaceId) => namespaceKv(kv, spaceId),
-		limitsFor
+		limitsFor,
+		setPluginFunctions: (plugin, definition) => {
+			const next = new Map(plugins);
+			if (definition) next.set(plugin, definition);
+			else next.delete(plugin);
+			current = build(next);
+			plugins.clear();
+			next.forEach((value, key) => plugins.set(key, value));
+		}
 	};
 	if (config.jobs !== false && config.lookups.listActions) module.jobs = createActionJobs(config.jobs ?? {}, module, config.lookups);
 	return module;

package/dist/modules/actions/runtime/fileKv.d.ts

@@ -0,0 +1,28 @@
+import { ActionKvAdapter } from '../types';
+export type FileKvOptions = {
+    /** The JSON file the store lives in — created, with its folder, on the first write. */
+    file: string;
+};
+export type FileKv = ActionKvAdapter & {
+    /** Resolves once everything written so far is on disk: for a shutdown, or a test that reads the file. */
+    flush: () => Promise<void>;
+};
+/**
+ * A key/value store in one JSON file: the `kv` server actions keep — saved layouts, counters, a source's cached answer —
+ * surviving a restart, for a deployment with no database. Nothing to install, and a file anybody can read, back up or
+ * edit by hand while the server is stopped.
+ *
+ * ```ts
+ * createServer({ action: { kv: createFileKv({ file: 'state/kv.json' }) } });
+ * ```
+ *
+ * The rules are the in-process store's, to the letter (`createMapKv`): the file is only where the map is kept. Every
+ * change is written whole, through a temporary file renamed over the old one, as soon as the change is made — changes
+ * that arrive while a write is under way are written together right after it, so a crash loses at most the writes
+ * of that instant and never leaves half a file. Entries past their lifetime are not written.
+ *
+ * ONE process: it reads the file when it starts and owns it after. Two processes on one file overwrite each other —
+ * replicas, or a server started with `workers`, use `createSqliteKv` (`@plitzi/sdk-server/sqlite`) or a database.
+ * And a whole file per change: right for what a site keeps, not for a counter bumped thousands of times a second.
+ */
+export declare const createFileKv: ({ file }: FileKvOptions) => FileKv;

package/dist/modules/actions/runtime/fileKv.js

@@ -0,0 +1,95 @@
+import { serverLog } from "../../../helpers/serverLog.js";
+import { createMapKv } from "./memoryKv.js";
+import { writeFileAtomic } from "../../../helpers/atomicFile.js";
+import path from "node:path";
+import fs from "node:fs";
+//#region src/modules/actions/runtime/fileKv.ts
+var isEntry = (value) => typeof value === "object" && value !== null && "value" in value && typeof value.value === "string" && (!("expiresAt" in value) || typeof value.expiresAt === "number");
+var load = (file) => {
+	if (!fs.existsSync(file)) return /* @__PURE__ */ new Map();
+	const refuse = (why) => /* @__PURE__ */ new Error(`createFileKv: ${file} is not a store it wrote (${why}). Move it aside, or point \`file\` elsewhere.`);
+	let parsed;
+	try {
+		parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch (error) {
+		throw refuse(error instanceof Error ? error.message : String(error));
+	}
+	if (typeof parsed !== "object" || parsed === null || !("format" in parsed) || parsed.format !== 1) throw refuse("no `format: 1`");
+	const entries = "entries" in parsed && typeof parsed.entries === "object" ? parsed.entries : null;
+	if (entries === null) throw refuse("no `entries`");
+	const now = Date.now();
+	const kept = Object.entries(entries).filter((pair) => isEntry(pair[1]) && (pair[1].expiresAt === void 0 || pair[1].expiresAt > now));
+	return new Map(kept);
+};
+/**
+* A key/value store in one JSON file: the `kv` server actions keep — saved layouts, counters, a source's cached answer —
+* surviving a restart, for a deployment with no database. Nothing to install, and a file anybody can read, back up or
+* edit by hand while the server is stopped.
+*
+* ```ts
+* createServer({ action: { kv: createFileKv({ file: 'state/kv.json' }) } });
+* ```
+*
+* The rules are the in-process store's, to the letter (`createMapKv`): the file is only where the map is kept. Every
+* change is written whole, through a temporary file renamed over the old one, as soon as the change is made — changes
+* that arrive while a write is under way are written together right after it, so a crash loses at most the writes
+* of that instant and never leaves half a file. Entries past their lifetime are not written.
+*
+* ONE process: it reads the file when it starts and owns it after. Two processes on one file overwrite each other —
+* replicas, or a server started with `workers`, use `createSqliteKv` (`@plitzi/sdk-server/sqlite`) or a database.
+* And a whole file per change: right for what a site keeps, not for a counter bumped thousands of times a second.
+*/
+var createFileKv = ({ file }) => {
+	const entries = load(file);
+	let dirty = false;
+	let failed = false;
+	/** The write under way, resolving to whether everything it took on reached the disk. */
+	let writing;
+	const document = () => {
+		const now = Date.now();
+		const live = [...entries].filter(([, entry]) => entry.expiresAt === void 0 || entry.expiresAt > now);
+		const body = {
+			format: 1,
+			entries: Object.fromEntries(live)
+		};
+		return `${JSON.stringify(body, null, 2)}\n`;
+	};
+	const drain = async () => {
+		while (dirty) {
+			dirty = false;
+			try {
+				await fs.promises.mkdir(path.dirname(file), { recursive: true });
+				await writeFileAtomic(file, document());
+			} catch (error) {
+				dirty = true;
+				failed = true;
+				serverLog.error("Actions", `kv file ${file} could not be written`, error);
+				return false;
+			}
+		}
+		return true;
+	};
+	const write = () => {
+		writing ??= new Promise((resolve) => {
+			queueMicrotask(resolve);
+		}).then(drain).finally(() => {
+			writing = void 0;
+			if (dirty && !failed) write();
+		});
+		return writing;
+	};
+	const changed = () => {
+		dirty = true;
+		failed = false;
+		write();
+	};
+	return {
+		...createMapKv(entries, changed),
+		flush: async () => {
+			failed = false;
+			while (writing !== void 0 || dirty) if (!await (writing ?? write())) throw new Error(`createFileKv: ${file} could not be written; the reason is in the log.`);
+		}
+	};
+};
+//#endregion
+export { createFileKv };

package/dist/modules/actions/runtime/fileKv.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/actions/runtime/memoryKv.d.ts

@@ -1,5 +1,28 @@
 import { StoreMethods } from '../../../core/server/fleet/channel';
 import { ActionKvAdapter } from '../types';
+/** A value and, when it has one, the instant (epoch ms) it stops being one. */
+export type KvEntry = {
+    value: string;
+    expiresAt?: number;
+};
 /** Every method of the store, for the copy a server's workers share (see `fleet/stores.ts`). */
 export declare const KV_METHODS: StoreMethods<ActionKvAdapter>;
+/**
+ * The store's rules over a map somebody holds: what `createMemoryKv` is, and what a store that keeps the map
+ * somewhere (`createFileKv`) is too — so the two answer identically and differ only in where the map lives.
+ *
+ * An adapter like any other: it stores strings and obeys no rules of its own. What a counter DOES lives in
+ * `createKvStore`, so the in-process store and a deployment's own behave identically rather than nearly so.
+ *
+ * `changed` is told after every write that changed the map — an expired entry swept or read past included.
+ */
+export declare const createMapKv: (entries: Map<string, KvEntry>, changed?: () => void) => ActionKvAdapter;
+/**
+ * The `kv` tasks' fallback store: in this process, and nowhere else — gone when it stops.
+ *
+ * Real enough for a single replica and for local work, and deliberately not pretending otherwise — a deployment
+ * running several replicas passes an adapter over something shared, because a counter that only counts its own
+ * replica is a rate limit that multiplies by the number of them. One that must survive a restart passes
+ * `createFileKv` (one process) or `createSqliteKv` (`@plitzi/sdk-server/sqlite`).
+ */
 export declare const createMemoryKv: () => ActionKvAdapter;