create-tinyjoin 0.0.5

package/LICENSE

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

@@ -0,0 +1,53 @@
+# create-tinyjoin
+
+Scaffold a small local todo app with TinyJoin, TypeScript, and Vite:
+
+```sh
+npm create tinyjoin@latest
+```
+
+The generated project is ready to run at its root and needs no database server,
+account, or credentials. Choose whether its todos should remain after reloads or
+start fresh each time.
+
+For agents and CI, every option can be supplied non-interactively:
+
+```sh
+npm create tinyjoin@latest -- --non-interactive \
+  --projectName my-tinyjoin-app \
+  --storage opfs \
+  --installAndRun false
+```
+
+Use `--list-options` for the machine-readable option catalog or `--help` for
+usage.
+
+`npm run build` assembles the publishable `create-tinyjoin` package under
+`dist/`.
+
+## Development
+
+```sh
+npm run typecheck       # generator and test TypeScript
+npm test                # CLI, template, and package-boundary tests
+npm run test:generated  # generated apps against published TinyJoin
+npm run test:e2e        # real generated-app behavior in Chromium
+```
+
+Run the local generator from this repository's parent directory with:
+
+```sh
+npm --prefix create-tinyjoin run local
+```
+
+This builds only the generator. The generated app installs the published
+TinyJoin package, so its native build toolchain is not required.
+
+To test unpublished changes from a neighboring TinyJoin source repository, use:
+
+```sh
+npm --prefix create-tinyjoin run local:source
+```
+
+That command builds and packs the sibling TinyJoin repository before starting
+the generator.

package/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import{existsSync as c}from"node:fs";import{dirname as l,join as r}from"node:path";import{fileURLToPath as p}from"node:url";import{createCLI as u,detectPackageManager as m}from"tinycreate";const g=r(l(p(import.meta.url)),"templates"),s=process.argv.slice(2),i=[{title:"Save data across reloads (recommended)",value:"opfs"},{title:"Start fresh each time",value:"memory"}],d={command:"npm create tinyjoin@latest --",nonInteractiveFlag:"--non-interactive",options:{projectName:{type:"string",required:!0},storage:{values:i.map(({value:e})=>e),required:!0,default:"opfs"},installAndRun:{values:[!0,!1],required:!0,recommendedForAgents:!1}}};(s.includes("--help")||s.includes("-h"))&&(console.log(`create-tinyjoin
+
+Interactively scaffold a TinyJoin application:
+  npm create tinyjoin@latest
+
+Run non-interactively:
+  npm create tinyjoin@latest -- --non-interactive \\
+    --projectName my-tinyjoin-app --storage opfs \\
+    --installAndRun false
+
+Agent and automation commands:
+  --list-options  Print the current option catalog as JSON
+  --help          Show this help`),process.exit(0)),s.includes("--list-options")&&(console.log(JSON.stringify(d,null,2)),process.exit(0));const f={welcomeMessage:`\u{1F389} Welcome to TinyJoin!
+`,questions:[{type:"text",name:"projectName",message:"Project name:",initial:"my-tinyjoin-app",validate:a},{type:"select",name:"storage",message:"Todo data:",choices:[...i],initial:0},{type:"confirm",name:"installAndRun",message:"Install dependencies and start the app?",initial:!0}],createContext:e=>{const t=String(e.projectName??"").trim(),n=a(t);if(n!==!0)throw new TypeError(n);const o=h(e.storage===0?"opfs":e.storage??"opfs","storage",["opfs","memory"]);return{projectName:t,installAndRun:e.installAndRun===!0||e.installAndRun==="true",storage:o,usesOpfs:o==="opfs",storageName:y(t),tinyjoinDependency:process.env.CREATE_TINYJOIN_DEPENDENCY??"^0.0.5"}},getFiles:()=>[{template:"README.md.hbs",output:"README.md",prettier:!0},{template:"AGENTS.md.hbs",output:"AGENTS.md",prettier:!0},{template:"client/package.json.hbs",output:"package.json",prettier:!0},{template:"client/.gitignore.hbs",output:".gitignore"},{template:"client/index.html.hbs",output:"index.html",prettier:!0},{template:"client/tsconfig.json.hbs",output:"tsconfig.json",prettier:!0},{template:"client/src/database.ts.hbs",output:"src/database.ts",prettier:!0},{template:"client/src/main.ts.hbs",output:"src/main.ts",prettier:!0},{template:"client/src/style.css.hbs",output:"src/style.css",prettier:!0}],templateRoot:g,installCommand:"{pm} install",devCommand:"{pm} run dev",workingDirectory:".",onSuccess:e=>{const t=m();console.log("Next steps:"),console.log(`  cd ${e}`),console.log(`  ${t} install`),console.log(`  ${t} run dev`)}};u(f).catch(e=>{console.error(e instanceof Error?e.message:String(e)),process.exit(1)});function a(e){return!/^[a-z0-9][a-z0-9._-]*$/i.test(e)||e==="."||e===".."?"Use letters, numbers, dots, dashes, or underscores without path separators.":c(r(process.cwd(),e))?`Directory "${e}" already exists. Choose a different name.`:!0}function h(e,t,n){const o=typeof e=="string"?e:"";if(!n.includes(o))throw new TypeError(`${j(t)} must be one of: ${n.join(", ")}.`);return o}function y(e){const t=e.toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"")||"app",n="tinyjoin-",o="-db-v1";return`${n}${t.slice(0,64-n.length-o.length)}${o}`}function j(e){return`${e.charAt(0).toUpperCase()}${e.slice(1)}`}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-tinyjoin",
+  "version": "0.0.5",
+  "author": "jamesgpearce",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tinyplex/create-tinyjoin.git"
+  },
+  "homepage": "https://tinyjoin.org",
+  "bugs": {
+    "url": "https://github.com/tinyplex/create-tinyjoin/issues"
+  },
+  "license": "MIT",
+  "description": "Scaffold a standalone TinyJoin browser database application.",
+  "keywords": [
+    "postgresql",
+    "local-first",
+    "webassembly",
+    "web-worker",
+    "app generator",
+    "scaffolding"
+  ],
+  "type": "module",
+  "bin": {
+    "create-tinyjoin": "cli.js"
+  },
+  "dependencies": {
+    "tinycreate": "^1.0.8"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "files": [
+    "cli.js",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/templates/AGENTS.md.hbs

@@ -0,0 +1,15 @@
+# {{projectName}}
+
+This is a generated TinyJoin TypeScript/Vite starter.
+
+- Run the app from this directory with `npm run dev`.
+- Keep database setup in `src/database.ts` and application UI in `src/main.ts`.
+- Keep schema setup safe to run again when the app reloads.
+- Use TinyJoin's `sql` tagged template or parameter arrays for application
+  values. Do not concatenate user input into SQL.
+- Generate stable row identifiers in application code.
+- Keep the database client open while the app is running and close it during
+  page teardown.
+- Validate changes with `npm run build`.
+
+Current TinyJoin documentation: https://tinyjoin.org

package/templates/README.md.hbs

@@ -0,0 +1,29 @@
+# {{projectName}}
+
+A small local todo app built with TinyJoin, TypeScript, and Vite.
+
+## Start it
+
+```sh
+npm install
+npm run dev
+```
+
+Your app will open at the address Vite prints in the terminal. It needs no
+database server, account, or credentials.
+
+{{#if usesOpfs}}
+Todos are saved locally in this browser and remain after a reload.
+{{else}}
+Todos are kept for the current visit and start fresh after a reload.
+{{/if}}
+
+## Start editing
+
+- `src/database.ts` opens the database and defines the `todos` table.
+- `src/main.ts` contains the todo UI and its queries.
+- `src/style.css` contains the app styles.
+
+Run `npm run build` to check the TypeScript and create a production build.
+
+Learn more at [tinyjoin.org](https://tinyjoin.org).

package/templates/client/.gitignore.hbs

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.env.local

package/templates/client/index.html.hbs

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="description"
+      content="A small local todo app built with TinyJoin"
+    />
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <main>
+      <header>
+        <p class="eyebrow">TinyJoin starter</p>
+        <h1>Todos</h1>
+        <p class="intro">
+          {{#if usesOpfs}}Your list is saved locally in this browser.{{else}}Your list starts fresh each time you load the app.{{/if}}
+        </p>
+      </header>
+
+      <form data-testid="todo-form">
+        <label for="todo-title">What needs doing?</label>
+        <div class="composer">
+          <input
+            id="todo-title"
+            data-testid="todo-title"
+            name="title"
+            type="text"
+            maxlength="120"
+            placeholder="Add a todo"
+            autocomplete="off"
+            required
+          />
+          <button type="submit">Add</button>
+        </div>
+      </form>
+
+      <p class="status" data-testid="status" role="status" aria-live="polite">
+        Opening your todos…
+      </p>
+      <p class="error" data-testid="error" role="alert" hidden></p>
+      <ul data-testid="todos" aria-live="polite" aria-busy="true"></ul>
+
+      <footer>
+        Built with <a href="https://tinyjoin.org">TinyJoin</a>.
+      </footer>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/client/package.json.hbs

@@ -0,0 +1,21 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "tinyjoin": "{{tinyjoinDependency}}"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vite": "^8.2.1"
+  }
+}

package/templates/client/src/database.ts.hbs

@@ -0,0 +1,29 @@
+import {create} from 'tinyjoin';
+
+export type Todo = {
+  id: string;
+  title: string;
+  done: boolean;
+};
+
+export type Database = Awaited<ReturnType<typeof create>>;
+
+export async function openDatabase(): Promise<Database> {
+  const database = await create(
+    {{#if usesOpfs}}
+    'opfs://{{storageName}}',
+    {{else}}
+    'memory://',
+    {{/if}}
+  );
+
+  await database.exec(`
+    CREATE TABLE IF NOT EXISTS todos (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      done BOOLEAN NOT NULL DEFAULT false
+    )
+  `);
+
+  return database;
+}

package/templates/client/src/main.ts.hbs

@@ -0,0 +1,159 @@
+import './style.css';
+
+import {openDatabase, type Database, type Todo} from './database';
+
+const form = requiredElement<HTMLFormElement>('[data-testid="todo-form"]');
+const titleInput = requiredElement<HTMLInputElement>(
+  '[data-testid="todo-title"]',
+);
+const todosElement = requiredElement<HTMLUListElement>('[data-testid="todos"]');
+const statusElement = requiredElement<HTMLElement>('[data-testid="status"]');
+const errorElement = requiredElement<HTMLElement>('[data-testid="error"]');
+
+async function start(): Promise<void> {
+  const database = await openDatabase();
+  const unsubscribe = database.subscribe({tables: ['todos']}, () => {
+    runAction(() => renderTodos(database));
+  });
+
+  addEventListener(
+    'pagehide',
+    () => {
+      unsubscribe();
+      void database.close();
+    },
+    {once: true},
+  );
+
+  form.addEventListener('submit', (event) => {
+    event.preventDefault();
+    const title = titleInput.value.trim();
+    if (!title) {
+      return;
+    }
+    runAction(async () => {
+      await database.sql`
+        INSERT INTO todos (id, title, done)
+        VALUES (${crypto.randomUUID()}, ${title}, ${false})
+      `;
+      form.reset();
+      titleInput.focus();
+    });
+  });
+
+  todosElement.addEventListener('change', (event) => {
+    const checkbox = event.target;
+    const id =
+      checkbox instanceof HTMLInputElement
+        ? checkbox.dataset.todoId
+        : undefined;
+    if (
+      !(checkbox instanceof HTMLInputElement) ||
+      checkbox.dataset.action !== 'toggle' ||
+      !id
+    ) {
+      return;
+    }
+    runAction(async () => {
+      await database.sql`
+        UPDATE todos SET done = ${checkbox.checked}
+        WHERE id = ${id}
+      `;
+    });
+  });
+
+  todosElement.addEventListener('click', (event) => {
+    const target = event.target;
+    const button =
+      target instanceof Element
+        ? target.closest<HTMLButtonElement>('button[data-action="delete"]')
+        : null;
+    const id = button?.dataset.todoId;
+    if (!id) {
+      return;
+    }
+    runAction(async () => {
+      await database.sql`DELETE FROM todos WHERE id = ${id}`;
+    });
+  });
+
+  await renderTodos(database);
+  titleInput.focus();
+}
+
+async function renderTodos(database: Database): Promise<void> {
+  todosElement.setAttribute('aria-busy', 'true');
+  const {rows} = await database.query<Todo>(
+    'SELECT id, title, done FROM todos ORDER BY title, id',
+  );
+  todosElement.replaceChildren(
+    ...(rows.length === 0 ? [createEmptyState()] : rows.map(createTodo)),
+  );
+  todosElement.setAttribute('aria-busy', 'false');
+  statusElement.textContent = 'Ready';
+}
+
+function createTodo(todo: Todo): HTMLLIElement {
+  const item = document.createElement('li');
+  item.className = `todo${todo.done ? ' is-done' : ''}`;
+  item.dataset.todoId = todo.id;
+
+  const label = document.createElement('label');
+  const checkbox = document.createElement('input');
+  checkbox.type = 'checkbox';
+  checkbox.checked = todo.done;
+  checkbox.dataset.action = 'toggle';
+  checkbox.dataset.todoId = todo.id;
+  checkbox.setAttribute(
+    'aria-label',
+    `Mark ${todo.title} as ${todo.done ? 'not done' : 'done'}`,
+  );
+
+  const title = document.createElement('span');
+  title.textContent = todo.title;
+  label.append(checkbox, title);
+
+  const deleteButton = document.createElement('button');
+  deleteButton.type = 'button';
+  deleteButton.className = 'delete';
+  deleteButton.dataset.action = 'delete';
+  deleteButton.dataset.todoId = todo.id;
+  deleteButton.setAttribute('aria-label', `Delete ${todo.title}`);
+  deleteButton.textContent = 'Delete';
+
+  item.append(label, deleteButton);
+  return item;
+}
+
+function createEmptyState(): HTMLLIElement {
+  const item = document.createElement('li');
+  item.className = 'empty';
+  item.textContent = 'No todos yet. Add your first one above.';
+  return item;
+}
+
+function runAction(action: () => Promise<unknown>): void {
+  clearError();
+  void action().catch(showError);
+}
+
+function clearError(): void {
+  errorElement.hidden = true;
+  errorElement.textContent = '';
+}
+
+function showError(error: unknown): void {
+  statusElement.textContent = 'Something went wrong.';
+  errorElement.hidden = false;
+  errorElement.textContent = error instanceof Error ? error.message : String(error);
+}
+
+function requiredElement<ElementType extends Element>(selector: string): ElementType {
+  const element = document.querySelector<ElementType>(selector);
+  if (!element) {
+    throw new Error(`Missing starter element: ${selector}`);
+  }
+  return element;
+}
+
+void start().catch(showError);

package/templates/client/src/style.css.hbs

@@ -0,0 +1,199 @@
+:root {
+  color: #20251f;
+  background: #f4f6f1;
+  font-family:
+    Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
+    sans-serif;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  min-width: 20rem;
+  min-height: 100vh;
+  margin: 0;
+}
+
+button,
+input {
+  font: inherit;
+}
+
+button {
+  cursor: pointer;
+}
+
+main {
+  width: min(36rem, calc(100% - 2rem));
+  margin: 0 auto;
+  padding: 5rem 0 3rem;
+}
+
+header {
+  margin-bottom: 2rem;
+}
+
+.eyebrow {
+  margin: 0 0 0.5rem;
+  color: #397253;
+  font-size: 0.78rem;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+h1 {
+  margin: 0;
+  font-family: Georgia, "Times New Roman", serif;
+  font-size: clamp(3rem, 12vw, 5rem);
+  line-height: 0.95;
+}
+
+.intro {
+  margin: 1rem 0 0;
+  color: #697066;
+}
+
+form {
+  padding: 1rem;
+  border: 1px solid #d7ddd3;
+  border-radius: 1rem;
+  background: #fff;
+  box-shadow: 0 1rem 3rem rgb(32 49 38 / 8%);
+}
+
+form label {
+  display: block;
+  margin-bottom: 0.65rem;
+  font-size: 0.85rem;
+  font-weight: 750;
+}
+
+.composer {
+  display: flex;
+  gap: 0.6rem;
+}
+
+.composer input {
+  min-width: 0;
+  flex: 1;
+  padding: 0.8rem 0.9rem;
+  border: 1px solid #cbd3c7;
+  border-radius: 0.7rem;
+  color: inherit;
+  background: #fbfcfa;
+}
+
+.composer input:focus {
+  border-color: #397253;
+  outline: 3px solid rgb(57 114 83 / 15%);
+}
+
+.composer button,
+.delete {
+  border: 0;
+  border-radius: 0.7rem;
+  font-weight: 750;
+}
+
+.composer button {
+  padding: 0.8rem 1.15rem;
+  color: #fff;
+  background: #397253;
+}
+
+.status,
+.error {
+  min-height: 1.4rem;
+  margin: 1rem 0 0.5rem;
+  color: #697066;
+  font-size: 0.85rem;
+}
+
+.error {
+  color: #a0382e;
+}
+
+ul {
+  display: grid;
+  gap: 0.65rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.todo,
+.empty {
+  border: 1px solid #d7ddd3;
+  border-radius: 0.85rem;
+  background: #fff;
+}
+
+.todo {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.8rem 0.9rem;
+}
+
+.todo label {
+  display: flex;
+  min-width: 0;
+  flex: 1;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.todo input {
+  width: 1.15rem;
+  height: 1.15rem;
+  accent-color: #397253;
+}
+
+.todo span {
+  overflow-wrap: anywhere;
+}
+
+.todo.is-done span {
+  color: #8a9088;
+  text-decoration: line-through;
+}
+
+.delete {
+  padding: 0.45rem 0.65rem;
+  color: #7b423c;
+  background: #f7ecea;
+}
+
+.empty {
+  padding: 2rem;
+  color: #7b8278;
+  text-align: center;
+}
+
+footer {
+  margin-top: 2rem;
+  color: #7b8278;
+  font-size: 0.82rem;
+  text-align: center;
+}
+
+a {
+  color: #397253;
+}
+
+@media (max-width: 32rem) {
+  main {
+    padding-top: 2.5rem;
+  }
+
+  .composer {
+    align-items: stretch;
+    flex-direction: column;
+  }
+}

package/templates/client/tsconfig.json.hbs

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "exactOptionalPropertyTypes": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022",
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts"]
+}