@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/server/modules/server-functions/application/usecases/scheduler.ts

@@ -0,0 +1,115 @@
+/**
+ * Scheduled Server Functions
+ * `createServerFn({ schedule })` registers the fn for periodic
+ * execution — `startScheduler` ticks once per minute and runs every
+ * descriptor whose cron expression matches. Standard 5-field cron:
+ * minute hour day-of-month month day-of-week, supporting `*`,
+ * step, value and `a-b` ranges — e.g. "star-slash-5 star star star star"
+ */
+
+import { getServerFn } from "./registry";
+
+const parseField = (field: string, min: number, max: number): Set<number> => {
+	const out = new Set<number>();
+	for (const part of field.split(",")) {
+		if (part === "*") {
+			for (let i = min; i <= max; i++) out.add(i);
+		} else if (part.startsWith("*/")) {
+			const step = Number(part.slice(2));
+			for (let i = min; i <= max; i += step) out.add(i);
+		} else if (part.includes("-")) {
+			const [a, b] = part.split("-").map(Number);
+			for (let i = a; i <= b; i++) out.add(i);
+		} else {
+			out.add(Number(part));
+		}
+	}
+	return out;
+};
+
+export const cronMatches = (expr: string, date: Date): boolean => {
+	const fields = expr.trim().split(/\s+/);
+	if (fields.length !== 5) return false;
+	const [min, hour, dom, month, dow] = fields;
+	return (
+		parseField(min, 0, 59).has(date.getMinutes()) &&
+		parseField(hour, 0, 23).has(date.getHours()) &&
+		parseField(dom, 1, 31).has(date.getDate()) &&
+		parseField(month, 1, 12).has(date.getMonth() + 1) &&
+		parseField(dow, 0, 6).has(date.getDay())
+	);
+};
+
+/** Scheduled descriptors — id → cron expression */
+const schedules = new Map<string, string>();
+
+export const registerSchedule = (id: string, expr: string): void => {
+	schedules.set(id, expr);
+};
+
+let timer: ReturnType<typeof setInterval> | undefined;
+let lastTick = -1;
+
+/**
+ * Scheduler persistence — an optional store records the last-run
+ * minute per job and a per-tick lock so multi-instance deployments
+ * run each schedule once (best-effort; KV stores without CAS may
+ * double-fire under a write race)
+ */
+export interface SchedulerStore {
+	get(key: string): number | undefined;
+	set(key: string, value: number): void;
+}
+
+export interface SchedulerOptions {
+	/** Shared store — enables cross-instance dedupe + restart resume */
+	store?: SchedulerStore;
+	/** Lock/persistence key prefix — default "sf:cron" */
+	prefix?: string;
+}
+
+let opts: SchedulerOptions = {};
+
+const tick = async (): Promise<void> => {
+	const now = new Date();
+	const minute = Math.floor(now.getTime() / 60000);
+	if (minute === lastTick) return;
+	const prefix = opts.prefix ?? "sf:cron";
+	// Distributed tick lock — first instance to write wins this minute
+	if (opts.store) {
+		const lockKey = `${prefix}:tick:${minute}`;
+		if (opts.store.get(lockKey) !== undefined) return;
+		opts.store.set(lockKey, minute);
+	}
+	lastTick = minute;
+	for (const [id, expr] of schedules) {
+		if (!cronMatches(expr, now)) continue;
+		// Per-job last-run — skip when another instance (or a previous
+		// process lifetime) already ran this job this minute
+		if (opts.store) {
+			const lastKey = `${prefix}:last:${id}`;
+			if (opts.store.get(lastKey) === minute) continue;
+			opts.store.set(lastKey, minute);
+		}
+		const descriptor = getServerFn(id);
+		if (!descriptor) continue;
+		const result = descriptor.handler({
+			data: undefined,
+			context: { request: new Request("http://cron"), params: {} },
+		});
+		void Promise.resolve(result).catch(() => {});
+	}
+};
+
+/** Start the minute-grain scheduler — call once at server boot */
+export const startScheduler = (options: SchedulerOptions = {}): void => {
+	if (timer) return;
+	opts = options;
+	timer = setInterval(() => void tick(), 15000);
+	timer.unref?.();
+};
+
+export const stopScheduler = (): void => {
+	if (timer) clearInterval(timer);
+	timer = undefined;
+};

package/src/server/modules/server-functions/domain/index.ts

@@ -0,0 +1,24 @@
+export * from "./models";
+export {
+	err,
+	errCode,
+	type FnError,
+	type FnResult,
+	type InferServerFn,
+	type InferServerFnError,
+	isErr,
+	isOk,
+	ok,
+	resultOf,
+} from "./operations/result";
+export {
+	deserialize,
+	isAsyncIterable,
+	isReadableStream,
+	serialize,
+} from "./operations/serialize";
+export {
+	NDJSON_CONTENT_TYPE,
+	readStreamResponse,
+	streamResponse,
+} from "./operations/stream";

package/src/server/modules/server-functions/domain/models/execution-result.ts

@@ -0,0 +1,18 @@
+/**
+ * Execution Result Model
+ * Wire format for server function responses
+ */
+
+export interface ServerFnSuccess<T> {
+	result: T;
+}
+
+export interface ServerFnFailure {
+	error: { code: string; message: string; data?: unknown };
+}
+
+export type ServerFnWireResult<T> = ServerFnSuccess<T> | ServerFnFailure;
+
+export const isServerFnFailure = <T>(
+	value: ServerFnWireResult<T>,
+): value is ServerFnFailure => "error" in value;

package/src/server/modules/server-functions/domain/models/index.ts

@@ -0,0 +1 @@
+export * from "./execution-result";

package/src/server/modules/server-functions/domain/operations/result.ts

@@ -0,0 +1,61 @@
+/**
+ * Result — typed error union for server functions. Return
+ * `ok(data)` / `err(code, message)` from handlers; the serialized
+ * envelope crosses the wire so clients branch without try/catch:
+ *
+ *   export const save = createServerFn(async (ctx, input) => {
+ *     if (!input.name) return err("VALIDATION", "name required");
+ *     return ok(await db.insert(input)); // Result<Row, FnError>
+ *   });
+ */
+
+export interface FnError {
+	code: string;
+	message: string;
+}
+
+export type FnResult<T, E = FnError> =
+	| { ok: true; data: T }
+	| { ok: false; error: E };
+
+export const ok = <T>(data: T): FnResult<T, never> => ({ ok: true, data });
+
+export const err = <E = FnError>(error: E): FnResult<never, E> => ({
+	ok: false,
+	error,
+});
+
+/** Convenience — err("VALIDATION", "name required") */
+export const errCode = (code: string, message: string): FnResult<never> =>
+	err({ code, message });
+
+/** Wrap an async op into a Result — exceptions become INTERNAL errors */
+export const resultOf = async <T>(
+	op: () => Promise<T>,
+): Promise<FnResult<T>> => {
+	try {
+		return ok(await op());
+	} catch (e) {
+		return err({
+			code: "INTERNAL",
+			message: e instanceof Error ? e.message : String(e),
+		});
+	}
+};
+
+/** Narrow helpers */
+export const isOk = <T, E>(r: FnResult<T, E>): r is { ok: true; data: T } =>
+	r.ok === true;
+export const isErr = <T, E>(r: FnResult<T, E>): r is { ok: false; error: E } =>
+	r.ok === false;
+
+/** Infer the data type a server fn resolves to — `InferServerFn<typeof save>` */
+export type InferServerFn<T> = T extends (...args: never[]) => Promise<infer R>
+	? R
+	: T extends (...args: never[]) => infer R
+		? R
+		: never;
+
+/** Infer the error type of a server fn returning FnResult */
+export type InferServerFnError<T> =
+	InferServerFn<T> extends FnResult<unknown, infer E> ? E : never;

package/src/server/modules/server-functions/domain/operations/serialize.ts

@@ -0,0 +1,134 @@
+/**
+ * Advanced Serialization
+ * Tagged serializer for server-function input/output — handles the
+ * values JSON can't: Date, BigInt, Map, Set, Uint8Array, Error,
+ * undefined. Streams and async iterables are NOT tagged inline —
+ * they travel as the response body via the streaming protocol
+ * (see stream.ts)
+ */
+
+const TAG = "$sf";
+
+type Json = null | boolean | number | string | Json[] | { [k: string]: Json };
+
+const b64encode = (buf: ArrayBufferLike): string => {
+	const bytes = new Uint8Array(buf);
+	let out = "";
+	for (let i = 0; i < bytes.length; i += 0x8000) {
+		out += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+	}
+	return btoa(out);
+};
+
+const b64decode = (b64: string): Uint8Array =>
+	Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+
+export const serialize = (value: unknown): Json => {
+	if (value === undefined) return { [TAG]: "undefined" };
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		return Number.isFinite(value)
+			? value
+			: { [TAG]: "number", v: String(value) };
+	}
+	if (typeof value === "string") return value;
+	if (typeof value === "bigint") return { [TAG]: "bigint", v: String(value) };
+	if (value instanceof Date) {
+		return { [TAG]: "date", v: value.toISOString() };
+	}
+	if (value instanceof Map) {
+		return {
+			[TAG]: "map",
+			v: [...value.entries()].map(
+				([k, v]) => [serialize(k), serialize(v)] as Json,
+			),
+		};
+	}
+	if (value instanceof Set) {
+		return { [TAG]: "set", v: [...value].map(serialize) };
+	}
+	if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+		const buf =
+			value instanceof ArrayBuffer
+				? value
+				: value.buffer.slice(
+						value.byteOffset,
+						value.byteOffset + value.byteLength,
+					);
+		return { [TAG]: "binary", v: b64encode(buf) };
+	}
+	if (value instanceof Error) {
+		return {
+			[TAG]: "error",
+			v: {
+				name: value.name,
+				message: value.message,
+				stack: value.stack ?? "",
+			},
+		};
+	}
+	if (Array.isArray(value)) return value.map(serialize);
+	if (typeof value === "object") {
+		const out: Record<string, Json> = {};
+		for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			out[k] = serialize(v);
+		}
+		return out;
+	}
+	return null;
+};
+
+const isTagged = (v: unknown): v is Record<string, unknown> & { v?: unknown } =>
+	typeof v === "object" && v !== null && TAG in v;
+
+export const deserialize = (value: Json): unknown => {
+	if (Array.isArray(value)) return value.map(deserialize);
+	if (typeof value === "object" && value !== null) {
+		if (isTagged(value)) {
+			const tag = value[TAG];
+			const v = value.v as Json;
+			switch (tag) {
+				case "undefined":
+					return undefined;
+				case "bigint":
+					return BigInt(v as string);
+				case "date":
+					return new Date(v as string);
+				case "number":
+					return Number(v);
+				case "map":
+					return new Map(
+						(v as [Json, Json][]).map(
+							([k, val]) =>
+								[deserialize(k), deserialize(val)] as [unknown, unknown],
+						),
+					);
+				case "set":
+					return new Set((v as Json[]).map(deserialize));
+				case "binary":
+					return b64decode(v as string);
+				case "error": {
+					const src = v as { name?: string; message?: string };
+					const err = new Error(src.message);
+					err.name = src.name ?? "Error";
+					return err;
+				}
+				default:
+					break;
+			}
+		}
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value)) out[k] = deserialize(v);
+		return out;
+	}
+	return value;
+};
+
+/** Detect the streaming-capable result kinds */
+export const isAsyncIterable = (
+	v: unknown,
+): v is AsyncIterable<unknown> | AsyncGenerator<unknown> =>
+	typeof v === "object" && v !== null && Symbol.asyncIterator in (v as object);
+
+export const isReadableStream = (v: unknown): v is ReadableStream =>
+	typeof v === "object" && v !== null && v instanceof ReadableStream;

package/src/server/modules/server-functions/domain/operations/stream.ts

@@ -0,0 +1,107 @@
+/**
+ * Server-Function Streaming Protocol
+ * NDJSON frames over the response body — lets a handler return a
+ * ReadableStream or AsyncIterable and have the client consume it as
+ * an async iterable (the TanStack "frame protocol" equivalent)
+ *
+ *   { "v": <serialized chunk> }\n   — next value
+ *   { "d": true }\n                — done
+ *   { "e": "<message>" }\n         — error
+ */
+
+import { deserialize, serialize } from "./serialize";
+
+export const NDJSON_CONTENT_TYPE = "application/x-ndjson";
+
+const encode = (frame: object): Uint8Array =>
+	new TextEncoder().encode(`${JSON.stringify(frame)}\n`);
+
+/** Serialize an async iterable / value-stream into an NDJSON body */
+export const streamResponse = (
+	source: AsyncIterable<unknown> | ReadableStream,
+): Response => {
+	const iter =
+		source instanceof ReadableStream
+			? (source as ReadableStream & AsyncIterable<unknown>)
+			: source;
+
+	const body = new ReadableStream<Uint8Array>({
+		async start(controller) {
+			try {
+				for await (const chunk of iter as AsyncIterable<unknown>) {
+					controller.enqueue(encode({ v: serialize(chunk) }));
+				}
+				controller.enqueue(encode({ d: true }));
+			} catch (error) {
+				controller.enqueue(
+					encode({
+						e: error instanceof Error ? error.message : "stream failed",
+					}),
+				);
+			} finally {
+				controller.close();
+			}
+		},
+	});
+
+	return new Response(body, {
+		headers: { "Content-Type": NDJSON_CONTENT_TYPE },
+	});
+};
+
+/** Decode an NDJSON body back into an async iterable of values */
+export const readStreamResponse = (
+	response: Response,
+): AsyncIterable<unknown> => {
+	const body = response.body;
+	if (!body) {
+		return {
+			async *[Symbol.asyncIterator]() {
+				/* empty */
+			},
+		};
+	}
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+
+	return {
+		async *[Symbol.asyncIterator]() {
+			try {
+				for (;;) {
+					const { done, value } = await reader.read();
+					if (done) {
+						const tail = buffer.trim();
+						if (tail) {
+							const frame = JSON.parse(tail) as {
+								v?: unknown;
+								e?: string;
+							};
+							if (frame.e) throw new Error(frame.e);
+							if (frame.v !== undefined) yield deserialize(frame.v as never);
+						}
+						return;
+					}
+					buffer += decoder.decode(value, { stream: true });
+					let nl = buffer.indexOf("\n");
+					while (nl !== -1) {
+						const line = buffer.slice(0, nl).trim();
+						buffer = buffer.slice(nl + 1);
+						nl = buffer.indexOf("\n");
+						if (!line) continue;
+						const frame = JSON.parse(line) as {
+							v?: unknown;
+							d?: boolean;
+							e?: string;
+						};
+						if (frame.e) throw new Error(frame.e);
+						if (frame.d) return;
+						if ("v" in frame) yield deserialize(frame.v as never);
+					}
+				}
+			} finally {
+				reader.releaseLock();
+			}
+		},
+	};
+};

package/src/server/modules/server-functions/index.ts

@@ -0,0 +1,3 @@
+export * from "./adapters/http/handler";
+export * from "./application";
+export * from "./domain";

package/src/server/modules/server-only/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Server-Only Boundary
+ * Guards that keep server code out of client bundles at runtime
+ */
+
+import { isServer } from "solid-js/web";
+
+export const assertServer = (hint = "server-only module"): void => {
+	if (!isServer) {
+		throw new Error(
+			`[solid-framework] ${hint} was executed in a client bundle. ` +
+				"Move it into a .server.ts file or import it only from server code.",
+		);
+	}
+};
+
+/**
+ * Wrap a function so it throws when invoked on the client
+ */
+export const serverOnly = <TArgs extends unknown[], TReturn>(
+	fn: (...args: TArgs) => TReturn,
+	hint?: string,
+): ((...args: TArgs) => TReturn) => {
+	return (...args: TArgs): TReturn => {
+		assertServer(hint ?? fn.name ?? "serverOnly function");
+		return fn(...args);
+	};
+};
+
+export { isServer };

package/src/server/node.ts

@@ -0,0 +1,10 @@
+/**
+ * Node-only server helpers — @wrikka/solid-framework/server/node
+ * These modules touch node builtins (fs/path/crypto); never import this
+ * file from isomorphic code (it must stay out of client bundles)
+ */
+
+// Durable filesystem cache store — survives process restarts
+export { createFsCacheStore } from "#app/modules/cache/adapters/fs";
+// Static file serving for `solid start` / plain node servers
+export { createStaticHandler } from "#app/modules/static";

package/src/server/shared/errors/index.ts

@@ -0,0 +1 @@
+export * from "./server-fn-error";

package/src/server/shared/errors/server-fn-error.ts

@@ -0,0 +1,27 @@
+/**
+ * Server Function Error
+ * Error type thrown on the client when a server function call fails
+ */
+
+import type { ServerFnErrorPayload } from "#server/types";
+
+export class ServerFnError extends Error {
+	readonly code: string;
+	readonly data?: unknown;
+
+	constructor(payload: ServerFnErrorPayload) {
+		super(payload.message);
+		this.name = "ServerFnError";
+		this.code = payload.code;
+		this.data = payload.data;
+	}
+
+	static fromJson(value: unknown): ServerFnError {
+		const payload = value as Partial<ServerFnErrorPayload>;
+		return new ServerFnError({
+			code: payload.code ?? "INTERNAL_ERROR",
+			message: payload.message ?? "Server function failed",
+			data: payload.data,
+		});
+	}
+}

package/src/server/shared/index.ts

@@ -0,0 +1,2 @@
+export * from "./errors";
+export * from "./types";

package/src/server/shared/types/index.ts

@@ -0,0 +1,5 @@
+export interface Result<T, E = Error> {
+	success: boolean;
+	data?: T;
+	error?: E;
+}

package/src/server/types/index.ts

@@ -0,0 +1,65 @@
+/**
+ * Server Domain Types
+ * Type-safe server functions, route loaders and server-only boundaries
+ */
+
+export type ServerFnMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface ServerFnContext {
+	request: Request;
+	params: Record<string, string>;
+	/** Middleware-injected values — `.middleware()` object returns merge here */
+	[key: string]: unknown;
+}
+
+export type ServerFnHandler<TInput, TOutput> = (input: {
+	data: TInput;
+	context: ServerFnContext;
+}) => Promise<TOutput> | TOutput;
+
+/**
+ * Standard-schema-compatible validator or plain parse function
+ */
+export type ServerFnValidator<TInput> =
+	| ((input: unknown) => TInput)
+	| { "~standard": { validate(input: unknown): unknown } };
+
+/**
+ * Server function middleware — runs between validation and the handler.
+ * Return a `Response` to short-circuit, a plain object to merge into
+ * `context`, or nothing to continue.
+ */
+export type ServerFnMiddleware = (ctx: {
+	data: unknown;
+	context: ServerFnContext;
+}) =>
+	| undefined
+	| Response
+	| Record<string, unknown>
+	| Promise<undefined | Response | Record<string, unknown>>;
+
+export interface ServerFnDescriptor<TInput = unknown, TOutput = unknown> {
+	id: string;
+	method: ServerFnMethod;
+	validator?: ServerFnValidator<TInput>;
+	middleware?: ServerFnMiddleware[];
+	handler: ServerFnHandler<TInput, TOutput>;
+}
+
+export interface LoaderContext {
+	request: Request;
+	params: Record<string, string>;
+}
+
+export interface RouteLoader<TOutput> {
+	key: string;
+	execute(context: LoaderContext): Promise<TOutput>;
+	read(): TOutput | undefined;
+	invalidate(): void;
+}
+
+export interface ServerFnErrorPayload {
+	code: string;
+	message: string;
+	data?: unknown;
+}

package/src/stores/adapters/analytics/index.ts

@@ -0,0 +1,5 @@
+// Store Module - Analytics Adapter
+// Clean Architecture: Monitoring and analytics
+
+// Re-export monitoring utilities
+export * from "./monitoring";