evikit 1.0.1 → 1.0.3

package/README.md

@@ -52,8 +52,8 @@ cd mysite
 npm init -y
 
 # Routing and validation.
-npm i accept-language classnames express evikit hoofd preact preact-iso valibot
-npm i -D cross-env vite vite-bundle-analyzer
+npm i accept-language classnames evikit express hoofd preact preact-iso valibot
+npm i -D @preact/preset-vite cross-env vite vite-bundle-analyzer
 
 # API documentation.
 npm i swagger-ui-express
@@ -68,25 +68,44 @@ Second, configure strict JSDoc type checking using TypeScript at `tsconfig.json`
 npx tsc --init --outDir dist --allowJs --checkJs --noEmit --esModuleInterop
 ```
 
+Third, open package.json and change `"type": "commonjs"` to `"type": "module"` because we want modern import syntax.
+
+Fourth, add a `.gitignore`. I suggest starting with:
+
+```
+node_modules
+/dist
+*~
+*swp
+.env
+*.db
+```
+
 ### Database schema
 
 Let's start by modelling a relational database schema. We have a question with multiple text choice options. Create `src/lib/db/schema.js`:
 
 ```js
 import { primary, references } from "evikit/db";
-import { number, integer, object, optional, pipe, string } from "valibot";
+import { integer, number, object, optional, pipe, string } from "valibot";
 
 export const Question = object({
   createdAt: pipe(number(), integer()),
-  id: pipe(optional(string(), () => crypto.randomUUID()), primary()),
-  text: string()
+  id: pipe(
+    optional(string(), () => crypto.randomUUID()),
+    primary(),
+  ),
+  text: string(),
 });
 
 export const Choice = object({
-  id: pipe(optional(string(), () => crypto.randomUUID()), primary()),
-  questionId: pipe(string(), references(Question, "id"))
-  text: string()
-  votes: pipe(number(), integer())
+  id: pipe(
+    optional(string(), () => crypto.randomUUID()),
+    primary(),
+  ),
+  questionId: pipe(string(), references(Question, "id")),
+  text: string(),
+  votes: pipe(number(), integer()),
 });
 ```
 
@@ -104,6 +123,8 @@ export const db = sqlite("data/local.db", { schema });
 - See QuestionIdServer below for an example of `select` with a join.
 - See VoteServer below for an example of `update` and `delete`.
 
+Create an empty `data/.gitkeep` file.
+
 ### Routing
 
 #### Language negotiation
@@ -114,10 +135,12 @@ Configure languages you're going to accept at `src/lib/index.js`:
 import acceptLanguage from "accept-language";
 
 export function acceptLanguages() {
-  acceptLanguage.languages(["en", "uk"]);
+  acceptLanguage.languages(["en"]);
 }
 ```
 
+Start with `en`. Add languages later when [translations](#translation) are ready.
+
 #### Error page
 
 Code an error page at `src/routes/error.js`:
@@ -146,13 +169,13 @@ export function ErrorPage({ children, error }) {
 Add an API router at `src/api.js` (uncomment the routes one by one when we add them later):
 
 ```js
-import { router } from "evikit/server";
+import { route, router } from "evikit/server";
 
 import pkg from "../package.json" with { type: "json" };
 import { acceptLanguages } from "./lib/index.js";
-// import { HomeServer } from "./routes/api/server.js";
 // import { ChoiceServer } from "./routes/api/choice/server.js";
 // import { QuestionIdServer } from "./routes/api/question/[id]/server.js";
+// import { HomeServer } from "./routes/api/server.js";
 // import { VoteServer } from "./routes/api/vote/server.js";
 
 acceptLanguages();
@@ -180,11 +203,16 @@ import { Route } from "preact-iso";
 import { acceptLanguages } from "./lib/index.js";
 import { ErrorPage } from "./routes/error.js";
 // import { HomePage } from "./routes/page.js";
-// import { QuestionIdPage } from "./routes/question/page.js";
+// import { QuestionIdPage } from "./routes/question/[id]/page.js";
 
 acceptLanguages();
 
-/** @param {{ dehydratedState?: ReturnType<import("evikit").dehydrate> | undefined, i18n?: ReturnType<import("evikit").useI18n> | undefined }} props */
+/** @param {{ lang?: string, url: string }} data */
+export async function prerender(data) {
+  return await ssr(App, data);
+}
+
+/** @param {{ dehydratedState?: ReturnType<import("evikit").dehydrate> | undefined, i18n: ReturnType<import("evikit").useI18n> }} props */
 function App({ dehydratedState, i18n }) {
   return h(
     Router,
@@ -195,11 +223,6 @@ function App({ dehydratedState, i18n }) {
   );
 }
 
-/** @param {{ lang?: string, url: string }} data */
-export async function prerender(data) {
-  return await ssr(App, data);
-}
-
 hydrate(App, "#app");
 ```
 
@@ -261,6 +284,8 @@ npx vite build
 
 You can add these commands (without npx) as `dev` and `build` scripts to your `package.json`.
 
+_TODO_ Why does `npx vite build` return 'Unable to detect prerender entry script' sometimes? Re-running fixed it for me.
+
 #### Production server
 
 Add production server at `index.js`:
@@ -363,7 +388,7 @@ export const HomeServer = {
 };
 ```
 
-Uncomment the `/api` route in `src/api.js`.
+Uncomment the `HomeServer` import and `/api` route in `src/api.js`.
 
 Render a Preact page route: `src/routes/page.js`:
 
@@ -381,11 +406,11 @@ export function HomePage() {
   return data
     ? ul(
         { class: "questions" },
-        questions.map((question) =>
+        data.Question.map((question) =>
           li(
             { key: question.id },
             a(
-              { href: `/polls/${encodeURIComponent(question.id)}` },
+              { href: `/question/${encodeURIComponent(question.id)}` },
               question.text,
             ),
           ),
@@ -395,7 +420,7 @@ export function HomePage() {
 }
 ```
 
-Uncomment the `HomePage` route in `src/app.js`.
+Uncomment the `HomePage` import and `/` route in `src/app.js`.
 
 #### Forms
 
@@ -427,7 +452,6 @@ Server endpoint: `src/routes/api/question/[id]/server.js`:
 ```js
 import { getI18n } from "evikit";
 import { endpoint, json, text } from "evikit/server";
-import { string } from "valibot";
 
 import { db } from "../../../../lib/db/index.js";
 import { QuestionIdGet } from "./types.js";
@@ -449,12 +473,11 @@ export const QuestionIdServer = {
 };
 ```
 
-Uncomment the `/question/:id` route in `src/api.js`.
+Uncomment the `QuestionIdServer` import and `/question/:id` route in `src/api.js`.
 
-Preact page route: `src/routes/question/[id]/page.js`:
+Preact page route: `src/routes/question/[id]/page.js` (note that we're outside the `api/` directory now):
 
 ```js
-import classNames from "classnames";
 import { h1, main, useApi, useEnhance, useI18n } from "evikit";
 import { useTitle } from "hoofd/preact";
 import { h } from "preact";
@@ -462,6 +485,7 @@ import { h } from "preact";
 import { ChoicePost } from "../../api/choice/types.js";
 import { QuestionIdGet } from "../../api/question/[id]/types.js";
 import { VotePost } from "../../api/vote/types.js";
+import { ErrorPage } from "../../error.js";
 
 export function QuestionIdPage() {
   const { data, error } = useApi(QuestionIdGet);
@@ -485,7 +509,7 @@ export function QuestionIdPage() {
 }
 ```
 
-Uncomment the `QuestionIdPage` route in `src/app.js`.
+Uncomment the `QuestionIdPage` import and `/question/:id` route in `src/app.js`.
 
 ##### Suggest own option
 
@@ -498,9 +522,9 @@ export const ChoicePost = {
   input: object({
     lang: string(),
     questionId: string(),
-    text: string()
-  })
-  outputs: { 302: string(), 400: string() }
+    text: string(),
+  }),
+  outputs: { 302: string(), 400: string() },
 };
 ```
 
@@ -510,9 +534,8 @@ Server endpoint: `src/routes/api/choice/server.js`:
 import { getI18n } from "evikit";
 import { endpoint, redirect, text } from "evikit/server";
 import { ok } from "node:assert/strict";
-import { object, string } from "valibot";
 
-import { db } from " ../../../lib/db/index.js";
+import { db } from "../../../lib/db/index.js";
 import { ChoicePost } from "./types.js";
 
 export const ChoiceServer = {
@@ -538,24 +561,25 @@ export const ChoiceServer = {
     return redirect(`/question/${encodeURIComponent(question.id)}`, 302, {
       cookies: {
         // Note: just an example. Use cookies sparingly, e.g. for session id.
-        ownSuggestionId: choice.id,
+        ownVoteQuestionId: { value: choice.questionId },
       },
     });
   }),
 };
 ```
 
-Uncomment the `/api/choice` route in `src/api.js`.
+Uncomment the `ChoiceServer` import and `/api/choice` route in `src/api.js`.
 
 Code a form view in place of `SUGGEST_FORM` in `src/routes/question/[id]/page.js`:
 
 ```js
-import { button, form, h2, input, label } from "evikit";
+import classNames from "classnames";
+import { button, form, h2, input, label, p } from "evikit";
 
 // ...
 
 form(
-  { action: "/api/choice", method: "POST", submit: suggestPost.onSubmit },
+  { action: "/api/choice", method: "POST", onSubmit: suggestPost.onSubmit },
   input({ name: "questionId", type: "hidden", value: data?.question.id }),
   h2({ class: "heading" }, i18n.gettext("Own choice")),
   p(
@@ -567,7 +591,7 @@ form(
     { class: classNames("btn", suggestPost.busy && "btn-disabled") },
     i18n.gettext("Suggest"),
   ),
-);
+),
 ```
 
 ##### Vote for choice
@@ -581,7 +605,7 @@ export const VotePost = {
   input: object({
     choiceId: string(),
     lang: string(),
-    ownSuggestionId: optional(string()), // Coming from cookie.
+    ownVoteQuestionId: optional(string()), // Coming from cookie.
   }),
   outputs: { 302: string(), 400: string() },
 };
@@ -592,7 +616,6 @@ Server endpoint: `src/routes/api/vote/server.js`:
 ```js
 import { getI18n } from "evikit";
 import { endpoint, redirect, text } from "evikit/server";
-import { string } from "valibot";
 
 import { db } from "../../../lib/db/index.js";
 import { VotePost } from "./types.js";
@@ -601,19 +624,16 @@ export const VoteServer = {
   post: endpoint(VotePost, async ({ input }) => {
     const i18n = await getI18n(input.lang);
 
-    if (input.choiceId == input.ownSuggestionId) {
-      return text(
-        i18n.gettext("You suggested this choice, it already has your vote"),
-        400,
-      );
-    }
-
     const Choice = db.Choice.select();
     const choice = Choice.find(({ id }) => id == input.choiceId);
     if (!choice) {
       return text(i18n.gettext("You didn't select a choice"), 400);
     }
 
+    if (choice.questionId == input.ownVoteQuestionId) {
+      return text(i18n.gettext("Already voted"), 400);
+    }
+
     db.Choice.update({
       set: { votes: choice.votes + 1 },
       where: { id: choice.id },
@@ -622,17 +642,17 @@ export const VoteServer = {
     // To delete a choice: `db.Choice.delete({ id: choice.id })`.
     // To delete multiple choices, pass an array of ids to `id`.
 
-    return redirect(`/question/${encodeURIComponent(question.id)}`, 302);
+    return redirect(`/question/${encodeURIComponent(choice.questionId)}`, 302);
   }),
 };
 ```
 
-Uncomment the `/api/vote` route in `src/api.js`.
+Uncomment the `VoteServer` import and `/api/vote` route in `src/api.js`.
 
 Code a form view in place of `VOTE_FORM` in `src/routes/question/[id]/page.js`:
 
 ```js
-import { button, form, input, label, li, ul } from "evikit";
+import { li, ul } from "evikit";
 
 // ...
 
@@ -643,7 +663,18 @@ form(
     data?.question.Choice.map((choice) =>
       li(
         { key: choice.id },
-        input({ id: choice.id, name: "choiceId", type: "radio" }),
+        input({
+          id: choice.id,
+          name: "choiceId",
+          type: "radio",
+          value: choice.id,
+        }),
+        label(
+          { for: choice.id },
+          choice.text,
+          ": ",
+          i18n.ngettext("%1 vote", "%1 votes", choice.votes, choice.votes),
+        ),
         label({ for: choice.id }, choice.text),
       ),
     ),
@@ -652,7 +683,7 @@ form(
     { class: classNames("btn", votePost.busy && "btn-disabled") },
     i18n.gettext("Vote"),
   ),
-);
+),
 ```
 
 ### Translation
@@ -745,6 +776,15 @@ npm i -D eslint-config-prettier prettier
 My `eslint.config.js`:
 
 ```js
+import { includeIgnoreFile } from "@eslint/compat";
+import js from "@eslint/js";
+import prettier from "eslint-config-prettier/flat";
+import perfectionist from "eslint-plugin-perfectionist";
+import { defineConfig } from "eslint/config";
+import globals from "globals";
+import { fileURLToPath } from "node:url";
+import ts from "typescript-eslint";
+
 export default defineConfig(
   includeIgnoreFile(fileURLToPath(new URL("./.gitignore", import.meta.url))),
   js.configs.recommended,

package/bin/evikit-extract.js

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync, globSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  globSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { basename } from "node:path";
 
 const pkg = JSON.parse(readFileSync("package.json", "utf-8"));
@@ -24,6 +30,9 @@ for (const output of globSync("po/*.po")) {
       stdio: "inherit",
     });
   } else {
+    if (existsSync(output)) {
+      unlinkSync(output);
+    }
     spawnSync(
       "msginit",
       [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "evikit",
   "description": "Preact/SQLite SSR framework for small web apps",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "exports": {
     ".": "./index.js",
@@ -22,6 +22,10 @@
   "license": "MIT",
   "dependencies": {
     "@fastify/busboy": "^3.2.0",
+    "@types/gettext-parser": "^9.0.0",
+    "@types/gettext.js": "^2.0.0",
+    "@types/lodash": "^4.17.24",
+    "@types/node": "^25",
     "@valibot/to-json-schema": "^1.7.0",
     "gettext-parser": "^9.0.2",
     "gettext.js": "^2.0.3",
@@ -38,10 +42,6 @@
   "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",