evikit 1.0.0

package/index.js

@@ -0,0 +1,208 @@
+import { toStatic } from "hoofd/preact";
+import { h } from "preact";
+import {
+  ErrorBoundary,
+  hydrate as iso,
+  Router as IsoRouter,
+  LocationProvider,
+  prerender,
+} from "preact-iso";
+import { locationStub } from "preact-iso/prerender";
+import { useState } from "preact/hooks";
+
+import {
+  a,
+  b,
+  button,
+  circle,
+  dialog,
+  div,
+  fieldset,
+  figure,
+  form,
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  header,
+  i,
+  img,
+  input,
+  label,
+  li,
+  main,
+  ol,
+  option,
+  p,
+  path,
+  select,
+  span,
+  svg,
+  title,
+  ul,
+} from "./html.js";
+import { getI18n, Po, RawI18nProvider, useI18n } from "./i18n.js";
+import {
+  dehydrate,
+  Hydrate,
+  QueryClient,
+  QueryClientProvider,
+  useQueryClient,
+} from "./query.js";
+import { queryApi, useApi } from "./use-api.js";
+import { useEnhance } from "./use-enhance.js";
+import { useStatus } from "./use-status.js";
+
+/**
+ * @param {(props: { dehydratedState?: ReturnType<import("./query.js").dehydrate> | undefined, i18n: ReturnType<import("./i18n.js").useI18n> } ) => import("preact").VNode} App
+ * @param {string} renderTarget
+ */
+export async function hydrate(App, renderTarget) {
+  if (typeof window !== "undefined") {
+    const app = document.querySelector(renderTarget);
+    if (!app) {
+      throw new Error(`${renderTarget} not found`);
+    }
+    let data;
+    const prerender = document.querySelector("#preact-prerender-data");
+    if (prerender) {
+      data = JSON.parse(prerender.textContent);
+      prerender.remove();
+    }
+
+    // If api and hydrate run in the same process, keep value from api.
+    // Avoid infinite recursion.
+    if (!Po.value) {
+      Po.set(
+        async (lang) =>
+          await (
+            await fetch(`${location.origin}/po/${encodeURIComponent(lang)}`)
+          ).json(),
+      );
+    }
+
+    iso(
+      h(App, {
+        dehydratedState: data?.dehydratedState,
+        // `window` matters. We want JSDOM navigator in tests, not Node.js one.
+        i18n: await getI18n(...window.navigator.languages),
+      }),
+      app,
+    );
+  }
+}
+
+/** @param {{ children?: import("preact").ComponentChildren, dehydratedState?: ReturnType<import("./query.js").dehydrate> | undefined, i18n: ReturnType<import("./i18n.js").useI18n> }} props */
+export function Router({ children, dehydratedState, i18n }) {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: { queries: { staleTime: 60 * 1000 } },
+      }),
+  );
+
+  return h(
+    RawI18nProvider,
+    { value: /** @type {any} */ (i18n) },
+    h(
+      QueryClientProvider,
+      { client: queryClient },
+      h(
+        Hydrate,
+        { state: dehydratedState },
+        h(
+          LocationProvider,
+          null,
+          h(ErrorBoundary, null, h(IsoRouter, null, children)),
+        ),
+      ),
+    ),
+  );
+}
+
+/**
+ * @param {(props: { dehydratedState?: ReturnType<import("./query.js").dehydrate> | undefined, i18n: ReturnType<import("./i18n.js").useI18n> }) => import("preact").VNode} App
+ * @param {{ lang?: string, url: string }} data
+ */
+export async function ssr(App, data) {
+  const origin = process.env["ORIGIN"] || "http://localhost:5173";
+  const i18n = await getI18n(...(data.lang ? [data.lang] : []));
+
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { staleTime: 0 } },
+  });
+  await queryClient.prefetchQuery(
+    queryApi({ lang: i18n.getLocale(), origin, path: data.url }),
+  );
+  const dehydratedState = dehydrate(queryClient, {
+    shouldRedactErrors: (error) => {
+      const { name } = /** @type {any} */ (error);
+      return !(Number(name) && name == "404");
+    },
+  });
+
+  locationStub(data.url);
+  const { html, links } = await prerender(h(/** @type {any} */ (App), {}), {
+    props: { dehydratedState, i18n },
+  });
+  const { metas, title } = toStatic();
+
+  return {
+    data: { ...data, dehydratedState },
+    head: {
+      elements: new Set(
+        metas.map((props) => ({
+          props: Object.fromEntries(
+            Object.entries(props).map(([name, content]) => [
+              name,
+              String(content),
+            ]),
+          ),
+          type: "meta",
+        })),
+      ),
+      lang: i18n.getLocale(),
+      title,
+    },
+    html,
+    links,
+  };
+}
+
+export { getI18n, useApi, useEnhance, useI18n, useQueryClient, useStatus };
+
+export {
+  a,
+  b,
+  button,
+  circle,
+  dialog,
+  div,
+  fieldset,
+  figure,
+  form,
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  header,
+  i,
+  img,
+  input,
+  label,
+  li,
+  main,
+  ol,
+  option,
+  p,
+  path,
+  select,
+  span,
+  svg,
+  title,
+  ul,
+};

package/jsdom-cookie.js

@@ -0,0 +1,5 @@
+// Workaround because jsdom has no fetch api of its own: https://github.com/jsdom/jsdom/issues/1724
+export const jsdomCookie = {
+  /** @type {string[]} Output of Headers.getSetCookie(). */
+  setCookie: [],
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "evikit",
+  "description": "Preact/SQLite SSR framework for small web apps",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./db": "./db.js",
+    "./server": "./server.js",
+    "./sqlite": "./sqlite.js",
+    "./testing": "./testing.js"
+  },
+  "bin": {
+    "evikit-extract": "bin/evikit-extract.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "format": "prettier --write . && eslint --fix .",
+    "lint": "prettier --check . && eslint ."
+  },
+  "author": "Denys Nykula <nykula@ukr.net>",
+  "license": "MIT",
+  "dependencies": {
+    "@fastify/busboy": "^3.2.0",
+    "@valibot/to-json-schema": "^1.7.0",
+    "gettext-parser": "^9.0.2",
+    "gettext.js": "^2.0.3",
+    "lodash": "^4.18.1",
+    "preact-render-to-string": "^6.7.0"
+  },
+  "peerDependencies": {
+    "accept-language": "^3.0.20",
+    "hoofd": "^1.7.3",
+    "preact": "^10.29.2",
+    "preact-iso": "^2.12.0",
+    "valibot": "^1.4.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.0",
+    "@eslint/js": "^10.0.1",
+    "@types/gettext-parser": "^9.0.0",
+    "@types/gettext.js": "^2.0.0",
+    "@types/lodash": "^4.17.24",
+    "@types/node": "^25",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-perfectionist": "^5.9.0",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.4"
+  }
+}

package/query.js

@@ -0,0 +1,231 @@
+import { createContext, h } from "preact";
+import { useContext, useEffect, useState } from "preact/hooks";
+
+/**
+ * @typedef {object} QueryState
+ * @property {any} data
+ * @property {number} dataUpdatedAt
+ * @property {unknown | null} error
+ * @property {boolean} isInvalidated
+ * @property {"error" | "loading" | "success"} status
+ */
+
+/**
+ * @typedef {{ state: QueryState, queryHash: string }[]} Queries
+ */
+
+/** @param {string[]} key */
+const QueryHash = (key) => key.map(encodeURIComponent).join("/");
+
+export class QueryClient {
+  state =
+    /** @type {{ queries: Queries, setQueries: (map: (queries: Queries) => Queries) => void }} */ ({
+      queries: [],
+      setQueries: (map) => {
+        this.state.queries = map(this.state.queries);
+      },
+    });
+
+  /** @param {{ defaultOptions: { queries: { staleTime: number }}}} props */
+  constructor({ defaultOptions }) {
+    this.defaultOptions = defaultOptions;
+  }
+
+  /** @param {{ queryKey?: string[] }} props */
+  invalidateQueries({ queryKey } = {}) {
+    if (queryKey) {
+      const queryHash = QueryHash(queryKey);
+      this.state.setQueries((queries) =>
+        queries.map((query) =>
+          query.queryHash == queryHash ||
+          query.queryHash.startsWith(queryHash + "/")
+            ? { ...query, state: { ...query.state, isInvalidated: true } }
+            : query,
+        ),
+      );
+    } else {
+      this.state.setQueries((queries) =>
+        queries.map((query) => ({
+          ...query,
+          state: { ...query.state, isInvalidated: true },
+        })),
+      );
+    }
+  }
+
+  /** @param {{ queryKey: string[], queryFn: () => Promise<any> }} props */
+  async prefetchQuery({ queryFn, queryKey }) {
+    const queryHash = QueryHash(queryKey);
+    /** @param {(queries: Queries) => QueryState} map */
+    const setQueryState = (map) =>
+      this.state.setQueries((queries) => {
+        const state = map(queries);
+        const existing = queries.find(
+          (query) => query.queryHash == queryHash,
+        )?.state;
+        return existing
+          ? queries.map((query) =>
+              query.state == existing ? { queryHash, state } : query,
+            )
+          : [...queries, { queryHash, state }];
+      });
+
+    const state = this.state.queries.find(
+      (query) => query.queryHash == queryHash,
+    )?.state;
+    if (
+      !state ||
+      (state.status != "loading" &&
+        (state.isInvalidated ||
+          state.dataUpdatedAt <
+            Date.now() - this.defaultOptions.queries.staleTime))
+    ) {
+      setQueryState(() => ({
+        data: state?.data ?? null,
+        dataUpdatedAt: state?.dataUpdatedAt ?? 0,
+        error: state?.error ?? null,
+        isInvalidated: false,
+        status: "loading",
+      }));
+      try {
+        const data = await queryFn();
+        setQueryState(() => ({
+          data,
+          dataUpdatedAt: Date.now(),
+          error: null,
+          isInvalidated: false,
+          status: "success",
+        }));
+      } catch (error) {
+        setQueryState((queries) => ({
+          data:
+            queries.find((query) => query.queryHash == queryHash)?.state.data ??
+            null,
+          dataUpdatedAt: Date.now(),
+          error,
+          isInvalidated: false,
+          status: "error",
+        }));
+      }
+    }
+  }
+}
+
+/**
+ * @param {QueryClient} queryClient
+ * @param {{ shouldRedactErrors: (error: unknown) => boolean}} options
+ */
+export function dehydrate(queryClient, options) {
+  return {
+    queries: queryClient.state.queries
+      .filter(
+        ({ state }) => !state.error || !options.shouldRedactErrors(state.error),
+      )
+      .map((query) => {
+        const error = /** @type {Error | undefined} */ (query.state.error);
+        return error && Number(error.name)
+          ? {
+              ...query,
+              state: {
+                ...query.state,
+                error: { message: error.message, name: error.name },
+              },
+            }
+          : error
+            ? {
+                ...query,
+                state: { ...query.state, error: { message: error.message } },
+              }
+            : query;
+      }),
+  };
+}
+
+const QueryClientContext = createContext(
+  /** @type {QueryClient} */ (/** @type {any} */ (undefined)),
+);
+
+/** @param {{ children?: import("preact").ComponentChildren, state: { queries: Queries } | undefined }} props */
+export function Hydrate(props) {
+  const originalQueryClient = useContext(QueryClientContext);
+  const [queries, setQueries] = useState(() =>
+    (props.state?.queries || []).map(({ queryHash, state }) => {
+      const error =
+        /** @type {{ message: string, name?: string } | undefined} */ (
+          state.error
+        );
+      return {
+        queryHash,
+        state: {
+          ...state,
+          error:
+            error && error.name
+              ? (() => {
+                  const e = new Error(error.message);
+                  e.name = error.name;
+                  return /** @type {unknown} */ (e);
+                })()
+              : error
+                ? /** @type {unknown} */ (new Error(error.message))
+                : error,
+        },
+      };
+    }),
+  );
+  const [queryClient, setQueryClient] = useState(() => {
+    originalQueryClient.state = { queries, setQueries };
+    return originalQueryClient;
+  });
+
+  useEffect(() => {
+    if (queryClient.state.queries != queries) {
+      const nextQueryClient = new QueryClient({
+        defaultOptions: queryClient.defaultOptions,
+      });
+      nextQueryClient.state = { queries, setQueries };
+      setQueryClient(nextQueryClient);
+    }
+  }, [queries]);
+
+  return h(QueryClientContext.Provider, { value: queryClient }, props.children);
+}
+
+/** @param {{ client: QueryClient, children?: import("preact").ComponentChildren }} props */
+export function QueryClientProvider(props) {
+  const [queries, setQueries] = useState(/** @type {Queries} */ ([]));
+  const [queryClient, setQueryClient] = useState(() => {
+    props.client.state = { queries, setQueries };
+    return props.client;
+  });
+
+  useEffect(() => {
+    const nextQueryClient = new QueryClient({
+      defaultOptions: queryClient.defaultOptions,
+    });
+    nextQueryClient.state = { queries, setQueries };
+    setQueryClient(nextQueryClient);
+  }, [queries]);
+
+  return h(QueryClientContext.Provider, { value: queryClient }, props.children);
+}
+
+/** @param {{ queryKey: string[], queryFn: () => Promise<any> }} props */
+export function useQuery({ queryFn, queryKey }) {
+  const queryClient = useQueryClient();
+  const queryHash = QueryHash(queryKey);
+  const query = queryClient.state.queries.find(
+    (query) => query.queryHash == queryHash,
+  );
+  const state = query?.state;
+
+  useEffect(() => {
+    queryClient.prefetchQuery({ queryFn, queryKey });
+  }, [queryHash, state?.status, state?.isInvalidated, state?.dataUpdatedAt]);
+
+  const { data, error, status } = query?.state || { status: "loading" };
+  return { data, error, status };
+}
+
+export function useQueryClient() {
+  return useContext(QueryClientContext);
+}

package/server-generic.d.ts

@@ -0,0 +1,95 @@
+/*
+Inspired by:
+
+- https://github.com/RobinTail/express-zod-api (API simplicity)
+- https://github.com/blomqma/next-rest-framework (response type checking)
+*/
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import {
+  type InferOutput,
+  type ObjectEntries,
+  type ObjectSchema,
+  StringSchema,
+} from "valibot";
+
+export type MethodServer = Record<
+  string,
+  {
+    handler(req: IncomingMessage, res: ServerResponse<IncomingMessage>): void;
+    input: ObjectSchema<ObjectEntries, undefined>;
+    outputs: Record<
+      number,
+      ObjectSchema<ObjectEntries, undefined> | StringSchema<undefined>
+    >;
+  }
+>;
+
+export type ServerEndpoint = <
+  Input extends ObjectEntries,
+  Status extends number,
+  Output extends ObjectEntries,
+  Outputs extends Record<
+    Status,
+    ObjectSchema<Output, undefined> | StringSchema<undefined>
+  >,
+  RouteType extends {
+    input: ObjectSchema<Input, undefined>;
+    outputs: Outputs;
+  },
+>(
+  routeType: RouteType,
+  handler: (req: {
+    input: InferOutput<RouteType["input"]>;
+  }) => Promise<
+    ServerOutput<
+      InferOutput<RouteType["outputs"][keyof RouteType["outputs"]]>,
+      keyof RouteType["outputs"]
+    >
+  >,
+) => {
+  handler(req: IncomingMessage, res: ServerResponse<IncomingMessage>): void;
+  input: typeof input;
+  outputs: Outputs;
+};
+
+export type ServerJson = <Output>(output: Output) => ServerOutput<Output, 200>;
+
+export type ServerRedirect = <Status extends number>(
+  location: string,
+  status: Status,
+  init?: { cookies: ServerCookies },
+) => ServerOutput<string, Status>;
+
+export type ServerText = <Status extends number>(
+  text: string,
+  status: Status,
+) => ServerOutput<string, Status>;
+
+type Assign<T, U> = Omit<T, keyof U> & U;
+
+type KnownContentType =
+  "application/json" | "application/x-www-form-urlencoded" | "text/plain";
+
+type ServerCookies = Record<string, { value: string }>;
+
+type ServerHeaders<ContentType extends KnownContentType> = Assign<
+  Record<string, string>,
+  Partial<Record<"Content-Type" | "content-type", ContentType>>
+>;
+
+interface ServerOutput<Output, Status extends number> {
+  contentType: ContentType;
+  cookies?: ServerCookies | undefined;
+  headers?: ServerHeaders<ContentType>;
+  output: Output;
+  status: Status;
+}
+
+interface ServerResponseInit<
+  Status extends number,
+  ContentType extends KnownContentType,
+> {
+  headers?: ServerHeaders<ContentType>;
+  status: Status;
+}

package/server.d.ts

@@ -0,0 +1,114 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+
+import type {
+  MethodServer,
+  ServerEndpoint,
+  ServerJson,
+  ServerRedirect,
+  ServerText,
+} from "./server-generic.js";
+
+export const endpoint: ServerEndpoint;
+
+export const json: ServerJson;
+
+export function listen(app: {
+  listen: (
+    port: number,
+    callback: () => void,
+  ) => {
+    close(): void;
+    on(event: "error", callback: (error: unknown) => void): void;
+  };
+}): void;
+
+export function production({
+  html,
+  prerender,
+}: {
+  html: string;
+  prerender({ lang, url }: { lang: string; url: string }): Promise<{
+    data: object;
+    head: {
+      elements: Set<{
+        props: Record<string, string>;
+        type: string;
+      }>;
+      lang: string;
+      title: string;
+    };
+    html: string;
+  }>;
+}): (
+  req: IncomingMessage,
+  res: ServerResponse<IncomingMessage>,
+) => Promise<void>;
+
+export const redirect: ServerRedirect;
+
+export function route(
+  path: string,
+  controller: MethodServer,
+): {
+  controller: MethodServer;
+  path: string;
+  pattern: URLPattern;
+};
+
+export function router(
+  {
+    pkg,
+  }: {
+    pkg: { name: string; version: string };
+  },
+  ...routes: {
+    controller: MethodServer;
+    path: string;
+    pattern: URLPattern;
+  }[]
+): {
+  onRequest: (
+    req: IncomingMessage,
+    res: ServerResponse<IncomingMessage>,
+    next?: () => void,
+  ) => Promise<void>;
+  openapi: {
+    info: { title: string; version: string };
+    openapi: string;
+    paths: Record<
+      string,
+      Record<
+        string,
+        {
+          parameters: {
+            in: string;
+            name: string;
+            required: boolean;
+            schema: { type: string };
+          }[];
+          requestBody?:
+            | undefined
+            | {
+                content: {
+                  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                  "application/x-www-form-urlencoded": { schema: any };
+                };
+              };
+          responses: Record<
+            string,
+            {
+              content: {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                "application/json": { schema: any };
+              };
+              description: string;
+            }
+          >;
+        }
+      >
+    >;
+    servers: { url: string }[];
+  };
+};
+
+export const text: ServerText;