@weft-js/start 0.0.0-stage → 0.1.1

package/src/db/sqlite.ts

@@ -0,0 +1,139 @@
+// SQLite for `@weft-js/start` (research 28 §1): Node's and Deno's `node:sqlite` or Bun's `bun:sqlite` behind Drizzle's
+// proxy driver, so no native binary and the same async API as Postgres. One connection, opened on the first statement
+// (`weft build` loads this module and must not touch a file). A transaction's body is async, so it holds a gate:
+// statements outside it wait, or a rollback would take another request's writes with it.
+
+// oxlint-disable-next-line typescript/triple-slash-reference -- an installed app's tsc doesn't include this file by itself, and it declares a module, so nothing can import it
+/// <reference path="./bun-sqlite.d.ts" />
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { SQLInputValue } from 'node:sqlite'
+import { drizzle, type SqliteRemoteDatabase } from 'drizzle-orm/sqlite-proxy'
+import { StartError } from '../data'
+import { gate, register, statements, touch, type DbHandle, type Migration } from './core'
+
+/** How Drizzle's proxy driver asks for rows. */
+export type Method = 'run' | 'all' | 'values' | 'get'
+
+interface Conn {
+  /** Array rows, as the proxy driver wants them. */
+  query(sql: string, params: unknown[], method: Method): unknown
+  exec(sql: string): void
+  close?(): void
+}
+
+/** The file open on this runtime's driver: Bun's, or `node:sqlite`. */
+export async function open(path: string): Promise<Conn> {
+  if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true })
+  const pick = (rows: unknown[][], method: Method) => (method === 'get' ? rows[0] : rows)
+  let conn: Conn
+  if ('Bun' in globalThis) {
+    const { Database } = await import('bun:sqlite')
+    const db = new Database(path, { create: true })
+    conn = {
+      query: (sql, params, method) => (method === 'run' ? void db.prepare(sql).run(...params) : pick(db.prepare(sql).values(...params), method)),
+      exec: sql => void db.run(sql),
+      close: () => db.close(),
+    }
+  } else {
+    const { DatabaseSync } = await import('node:sqlite')
+    const db = new DatabaseSync(path)
+    conn = {
+      query: (sql, params, method) => {
+        const s = db.prepare(sql)
+        if (method === 'run') return void s.run(...(params as SQLInputValue[]))
+        s.setReturnArrays(true)
+        return pick(s.all(...(params as SQLInputValue[])) as unknown as unknown[][], method)
+      },
+      exec: sql => db.exec(sql),
+      close: () => db.close(),
+    }
+  }
+  if (path !== ':memory:') conn.exec('pragma journal_mode = wal')
+  conn.exec('pragma foreign_keys = on; pragma busy_timeout = 5000')
+  return conn
+}
+
+/** `createDb` on SQLite: the schema, the file, and whether to migrate on first use. */
+export interface SqliteOptions<S extends Record<string, unknown>> {
+  schema: S
+  /** `file:.data/app.db` (the default), a path, or `:memory:`. */
+  url?: string
+  /** Apply `drizzle/` before the first statement a request runs (default true). */
+  migrate?: boolean
+}
+
+/** Drizzle over a local file, with `$weft` for the framework's own needs. */
+export type SqliteDb<S extends Record<string, unknown>> = SqliteRemoteDatabase<S> & { $weft: DbHandle }
+
+/** A Drizzle client on a SQLite file, with this app's migrations and write tracking. */
+export function createDb<S extends Record<string, unknown>>({ schema, url = 'file:.data/app.db', migrate = true }: SqliteOptions<S>): SqliteDb<S> {
+  if (/^[a-z][a-z0-9+.-]+:\/\//i.test(url) && !url.startsWith('file:'))
+    throw new StartError('Q013', `\`@weft-js/start/db/sqlite\` can't open \`${url.replace(/\/\/.*@/, '//…@')}\``, 'use `file:<path>`, or `createDb` from `@weft-js/start/db/postgres` for a Postgres URL')
+  const path = url.replace(/^file:/, '')
+  let conn: Promise<Conn> | undefined
+  const connect = () => (conn ??= open(path).catch(e => { conn = undefined; throw e }))
+  const inside = new AsyncLocalStorage<boolean>()
+  let held: Promise<unknown> = Promise.resolve()
+  const handle: DbHandle = {
+    dialect: 'sqlite',
+    exempt: new Set(),
+    async migrate(list: Migration[]) {
+      const c = await connect()
+      c.exec('create table if not exists __weft_migrations (tag text primary key, at integer not null)')
+      const done = new Set((c.query('select tag from __weft_migrations', [], 'values') as string[][]).map(r => r[0]))
+      for (const m of list) {
+        if (done.has(m.tag)) continue
+        c.exec('begin')
+        try {
+          for (const s of statements(m.sql)) c.exec(s)
+          c.query('insert into __weft_migrations values (?, ?)', [m.tag, Date.now()], 'run')
+          c.exec('commit')
+        } catch (e) {
+          c.exec('rollback')
+          throw e
+        }
+      }
+    },
+    changes: (tables, o) => import('./changes-sqlite').then(m => m.sqliteChanges({ ...o, path, open, tables })),
+  }
+  const ready = gate(handle, migrate)
+  const run = async (sql: string, params: unknown[], method: Method) => {
+    touch(handle, sql)
+    await ready()
+    const c = await connect()
+    if (!inside.getStore()) await held
+    return { rows: c.query(sql, params, method) as unknown[] }
+  }
+  const batch = async (list: { sql: string; params: unknown[]; method: Method }[]) => {
+    await ready()
+    const c = await connect()
+    await held
+    c.exec('begin')
+    try {
+      const out = list.map(q => (touch(handle, q.sql), { rows: c.query(q.sql, q.params, q.method) as unknown[] }))
+      c.exec('commit')
+      return out
+    } catch (e) {
+      c.exec('rollback')
+      throw e
+    }
+  }
+  const db = drizzle(run, batch, { schema })
+  const transaction = db.transaction.bind(db)
+  db.transaction = (async (...args: Parameters<typeof transaction>) => {
+    if (inside.getStore()) return transaction(...args)
+    await ready()
+    const before = held
+    let release!: () => void
+    held = new Promise<void>(ok => { release = ok })
+    await before
+    try {
+      return await inside.run(true, () => transaction(...args))
+    } finally {
+      release()
+    }
+  }) as typeof db.transaction
+  return register(db, handle)
+}

package/src/derive.d.mts

@@ -0,0 +1,16 @@
+/** The text with HTML entities decoded. */
+export function decode(text: string): string
+/** One line of plain text: whitespace collapsed, no list marker in front. */
+export function cleanText(text: string): string
+/** At most `max` characters, cut at a sentence or a word. */
+export function truncate(text: string, max?: number): string
+/** `undefined`, or why this text isn't a description a person would read. */
+export function descriptionProblem(text: string): string | undefined
+/** A page's title and description, as a person would pick them out of its HTML. */
+export function pageText(html: string): { title?: string; description?: string }
+/** The site's URL, from its config or from what the host says about this deploy. */
+export function deployUrl(site: { url?: string | undefined } | undefined, env?: Record<string, string | undefined>): string | undefined
+/** The card title's font size, smaller for a longer title. */
+export function cardTitleSize(title: string): number
+/** `paths` in pages that each fit in a response header. */
+export function pathPages(paths: string[], max?: number): string[][]

package/src/derive.mjs

@@ -0,0 +1,140 @@
+// What a page's HTML says about itself (research 20 §10): the automatic layer under route `meta`. A route that sets no
+// title gets its `h1`, one that sets no description gets its first real paragraph, cleaned and cut at a sentence. Pure
+// functions on a string, server-side only: `weft check` runs the same `descriptionProblem` on what a route wrote.
+
+const SKIP = new Set(['script', 'style', 'template', 'noscript', 'svg', 'math', 'nav', 'aside', 'footer', 'pre', 'figure', 'table', 'ul', 'ol', 'dl', 'details', 'button', 'select', 'textarea', 'form', 'dialog', 'iframe', 'canvas', 'object'])
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr'])
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', rsquo: '’', lsquo: '‘', ldquo: '“', rdquo: '”', middot: '·', copy: '©', reg: '®', trade: '™', times: '×', rarr: '→', larr: '←' }
+
+/** `&amp;`, `&#39;`, `&#x27;` → their characters. An unknown name stays as written. */
+export const decode = text => text.replace(/&(#\d+|#x[\da-f]+|[a-z]+);/gi, (all, e) => {
+  if (e[0] !== '#') return ENTITIES[e] ?? all
+  const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))
+  return n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : ''
+})
+
+/** One line of plain text: whitespace collapsed, no list marker in front, no space before punctuation. */
+export const cleanText = text => text
+  .replace(/\s+/g, ' ')
+  .replace(/\s+([.,;:!?)])(?=\s|$)/g, '$1')
+  .trim()
+  .replace(/^(?:[-*•‣–—]\s+|\d{1,3}[.)]\s+)+/, '')
+
+/** Not the end of a sentence, though it ends in a full stop. */
+const ABBREVIATION = /(?:^|[\s(])(?:e\.g|i\.e|etc|vs|cf|approx|no|fig|[A-Z])\.$/
+
+/**
+ * At most `max` characters: whole sentences when the first ones fit (past a third of `max`, so one short sentence
+ * isn't all that's left), else whole words and an ellipsis. Never cuts inside a word.
+ */
+export function truncate(text, max = 155) {
+  if (text.length <= max) return text
+  const head = text.slice(0, max + 1)
+  let end = -1
+  for (const m of head.matchAll(/[.!?…]["'”’)]?(?=\s)/g)) {
+    const at = m.index + m[0].length
+    if (at >= max / 3 && at <= max && !ABBREVIATION.test(head.slice(0, at))) end = at
+  }
+  if (end > 0) return head.slice(0, end)
+  const cut = head.slice(0, max).replace(/\s+\S*$/, '')
+  return cut.replace(/[\s,;:(–—-]+$/, '') + '…'
+}
+
+/** `undefined`, or why this text isn't a description a person would read: markup, code, a list item or a fragment. */
+export function descriptionProblem(text) {
+  const s = text.trim()
+  if (/^(?:[-*•+]\s|\d{1,3}[.)]\s|#{1,6}\s|>\s)/.test(s)) return 'it starts with a markdown list marker or heading'
+  if (/<\/?[a-z][^>]*>?|\/>|=>|\w\(\)|[{}]|`|\]\(|\bx = </i.test(s)) return 'it holds code or markup'
+  if ((s.match(/[<>=;$[\]{}()|\\]/g)?.length ?? 0) / Math.max(s.length, 1) > 0.05) return 'it is mostly symbols, which reads as code'
+  if (/\s[.,;:!?)](?=\s|$)/.test(s)) return 'it has a space before punctuation, the mark of inline code that was stripped out'
+  if (s.length && !/[.!?…"'”’)]$/.test(s) && s.length > 100) return 'it stops mid-sentence'
+  if (/^[a-z]/.test(s) && !/^[a-z][\w.-]*[A-Z@/:]|^[a-z]+:/.test(s)) return 'it starts in lower case, like a fragment of a longer sentence'
+  return undefined
+}
+
+/** A paragraph worth quoting: prose of some length, with no code in it. */
+const prose = text => text.length >= 40 && text.includes(' ') && !descriptionProblem(truncate(text))
+
+function tokens(html) {
+  const out = []
+  const re = /<!--[\s\S]*?-->|<(\/?)([a-zA-Z][\w:-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/g
+  let at = 0
+  for (let m; (m = re.exec(html)); at = re.lastIndex) {
+    if (m.index > at) out.push({ text: html.slice(at, m.index) })
+    if (m[2]) out.push({ close: !!m[1], tag: m[2].toLowerCase(), attrs: m[3] })
+  }
+  if (at < html.length) out.push({ text: html.slice(at) })
+  return out
+}
+
+const hidden = attrs => /\s(?:hidden|aria-hidden=(?:"true"|'true'|true))(?:[\s/]|$)/.test(attrs)
+
+/**
+ * The page's own words: `{ title, description }`, either missing when the page doesn't have one. Reads `<main>` when
+ * there is one, so a header or a footer in a layout can't speak for the page. The title is the `h1`, or with none the
+ * first `h2` or `h3`; the description is the first paragraph after the `h1` that reads as prose.
+ */
+export function pageText(html) {
+  const open = /<main\b/i.exec(html)
+  const end = html.toLowerCase().lastIndexOf('</main>')
+  const region = open ? html.slice(open.index, end > open.index ? end : undefined) : html
+  let title, heading, description, skip, grab, buffer = ''
+  const done = t => {
+    const text = cleanText(decode(buffer))
+    grab = undefined
+    if (t === 'p') { if (prose(text)) description ??= truncate(text) }
+    else if (t !== 'h1') heading ??= text || undefined
+    else if (text && !title) { title = text; description = undefined } // the description is what follows the title
+  }
+  for (const t of tokens(region)) {
+    if (skip) {
+      if (t.tag === skip.tag && !VOID.has(t.tag) && !/\/\s*$/.test(t.attrs ?? '')) skip.depth += t.close ? -1 : 1
+      if (!skip.depth) skip = undefined
+      continue
+    }
+    if (t.text !== undefined) { if (grab) buffer += t.text; continue }
+    if (!t.close && (SKIP.has(t.tag) || hidden(t.attrs)) && !VOID.has(t.tag) && !/\/\s*$/.test(t.attrs)) {
+      skip = { tag: t.tag, depth: 1 }
+      continue
+    }
+    if (grab) {
+      if (t.close && t.tag === grab) done(t.tag)
+      else if (t.tag === 'br') buffer += ' '
+      continue
+    }
+    if (!t.close && /^(?:h1|h2|h3|p)$/.test(t.tag)) { grab = t.tag; buffer = '' }
+    if (title && description) break
+  }
+  return { title: title ?? heading, description }
+}
+
+/**
+ * The site's public origin, when something says what it is: `site.url`, `WEFT_SITE_URL`, or what the host sets on a
+ * deploy. No request is involved, so the answer can be trusted and written into a page a CDN keeps.
+ */
+export function deployUrl(site, env = {}) {
+  if (site?.url) return site.url
+  const https = host => host && `https://${host}`
+  return env.WEFT_SITE_URL
+    || https(env.VERCEL_PROJECT_PRODUCTION_URL) || https(env.VERCEL_URL)
+    || env.URL // Netlify
+    || env.CF_PAGES_URL || env.RENDER_EXTERNAL_URL
+    || https(env.RAILWAY_PUBLIC_DOMAIN)
+    || (env.FLY_APP_NAME && `https://${env.FLY_APP_NAME}.fly.dev`)
+    || undefined
+}
+
+/** The built-in card's title size: bigger type for a shorter title. */
+export const cardTitleSize = title => (title.length <= 24 ? 92 : title.length <= 44 ? 76 : title.length <= 70 ? 62 : 52)
+
+/** `paths` in pages that each fit in a response header, with room for the link to the next page. */
+export function pathPages(paths, max = 6000) {
+  const pages = [[]]
+  let size = 0
+  for (const p of paths) {
+    if (size + p.length + 1 > max) { pages.push([]); size = 0 }
+    pages.at(-1).push(p)
+    size += p.length + 1
+  }
+  return pages
+}

package/src/dev-runtime.mjs

@@ -0,0 +1,42 @@
+// `weft dev` for an app with sockets on Bun and Deno. Nitro's dev server assumes a Node worker for websockets: its
+// entry takes crossws's Node adapter, which refuses to load there, and a worker on either runtime can't take the
+// upgrade. So the app runs in Vite's own process (the `self` runner), where Vite's HTTP server hands the upgrade over
+// and the adapter works. Node, and any app without a channel or sharedState, gets none of this.
+
+const alternate = Boolean(process.versions.bun || process.versions.deno)
+
+export const devRunner = sockets => (alternate && sockets ? 'self' : undefined)
+
+const GUARD = /if \("Deno" in globalThis \|\| "Bun" in globalThis\) throw new Error\([^)]*\);?/
+
+export const devSockets = () => ({
+  name: 'weft:dev-sockets',
+  apply: 'serve',
+  enforce: 'post',
+  configResolved(config) {
+    for (const [name, environment] of Object.entries(config.environments)) {
+      const create = environment.dev?.createEnvironment
+      if (!create || environment.consumer !== 'server') continue
+      const release = hold(name)
+      environment.dev.createEnvironment = async (...args) => release(await create(...args))
+    }
+  },
+  transform: {
+    filter: { id: /crossws/, code: 'incompatible environment' },
+    handler: code => code.replace(GUARD, ''),
+  },
+})
+
+// Nitro can name an environment to the runner before Vite has made it. Across a process that takes long enough, but
+// `self` answers at once: the first request goes to nothing and the environment hangs for good. So each one is held
+// until it exists, and `init` names it again. (The worker keeps these on globalThis, and `self` is this process.)
+const HELD = { hasEvaluated: () => false, reload: async () => {}, fetch: () => Promise.resolve(new Response('starting', { status: 503 })) }
+
+function hold(name) {
+  const environments = (globalThis.__nitro_vite_envs__ ??= {})
+  environments[name] = HELD
+  return environment => {
+    environments[name] = undefined
+    return environment
+  }
+}