on-zero 0.1.21 → 0.1.23

package/src/generate.ts

@@ -0,0 +1,490 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+
+const hash = (s: string) => createHash('sha256').update(s).digest('hex')
+
+let generateCache: Record<string, string> = {}
+let generateCachePath = ''
+
+function getCacheDir() {
+  let dir = process.cwd()
+  while (dir !== '/') {
+    const nm = resolve(dir, 'node_modules')
+    if (existsSync(nm)) {
+      const cacheDir = resolve(nm, '.on-zero')
+      if (!existsSync(cacheDir)) {
+        mkdirSync(cacheDir, { recursive: true })
+      }
+      return cacheDir
+    }
+    dir = resolve(dir, '..')
+  }
+  return null
+}
+
+function loadCache() {
+  const cacheDir = getCacheDir()
+  if (!cacheDir) return
+  generateCachePath = resolve(cacheDir, 'generate-cache.json')
+  try {
+    generateCache = JSON.parse(readFileSync(generateCachePath, 'utf-8'))
+  } catch {
+    generateCache = {}
+  }
+}
+
+function saveCache() {
+  if (generateCachePath) {
+    writeFileSync(generateCachePath, JSON.stringify(generateCache) + '\n', 'utf-8')
+  }
+}
+
+function writeFileIfChanged(filePath: string, content: string): boolean {
+  const contentHash = hash(content)
+  const cachedHash = generateCache[filePath]
+
+  if (cachedHash === contentHash && existsSync(filePath)) {
+    return false
+  }
+
+  writeFileSync(filePath, content, 'utf-8')
+  generateCache[filePath] = contentHash
+  return true
+}
+
+function generateModelsFile(modelFiles: string[]) {
+  const modelNames = modelFiles.map((f) => basename(f, '.ts')).sort()
+  const getImportName = (name: string) => (name === 'user' ? 'userPublic' : name)
+
+  const imports = modelNames
+    .map((name) => `import * as ${getImportName(name)} from '../models/${name}'`)
+    .join('\n')
+
+  const sortedByImportName = [...modelNames].sort((a, b) =>
+    getImportName(a).localeCompare(getImportName(b))
+  )
+  const modelsObj = `export const models = {\n${sortedByImportName.map((name) => `  ${getImportName(name)},`).join('\n')}\n}`
+
+  const hmrBoundary = `
+if (import.meta.hot) {
+  import.meta.hot.accept()
+}
+`
+
+  return `// auto-generated by: on-zero generate\n${imports}\n\n${modelsObj}\n${hmrBoundary}`
+}
+
+function generateTypesFile(modelFiles: string[]) {
+  const modelNames = modelFiles.map((f) => basename(f, '.ts')).sort()
+  const getSchemaName = (name: string) => (name === 'user' ? 'userPublic' : name)
+
+  const typeExports = modelNames
+    .map((name) => {
+      const pascalName = name.charAt(0).toUpperCase() + name.slice(1)
+      const schemaName = getSchemaName(name)
+      return `export type ${pascalName} = TableInsertRow<typeof schema.${schemaName}>\nexport type ${pascalName}Update = TableUpdateRow<typeof schema.${schemaName}>`
+    })
+    .join('\n\n')
+
+  return `import type { TableInsertRow, TableUpdateRow } from 'on-zero'\nimport type * as schema from './tables'\n\n${typeExports}\n`
+}
+
+function generateTablesFile(modelFiles: string[]) {
+  const modelNames = modelFiles.map((f) => basename(f, '.ts')).sort()
+  const getExportName = (name: string) => (name === 'user' ? 'userPublic' : name)
+
+  const exports = modelNames
+    .map((name) => `export { schema as ${getExportName(name)} } from '../models/${name}'`)
+    .join('\n')
+
+  return `// auto-generated by: on-zero generate\n// this is separate from models as otherwise you end up with circular types :/\n\n${exports}\n`
+}
+
+function generateReadmeFile() {
+  return `# generated
+
+this folder is auto-generated by on-zero. do not edit files here directly.
+
+## what's generated
+
+- \`models.ts\` - exports all models from ../models
+- \`types.ts\` - typescript types derived from table schemas
+- \`tables.ts\` - exports table schemas for type inference
+- \`groupedQueries.ts\` - namespaced query re-exports for client setup
+- \`syncedQueries.ts\` - namespaced syncedQuery wrappers for server setup
+
+## usage guidelines
+
+**do not import generated files outside of the data folder.**
+
+### queries
+
+write your queries as plain functions in \`../queries/\` and import them directly:
+
+\`\`\`ts
+// ✅ good - import from queries
+import { channelMessages } from '~/data/queries/message'
+\`\`\`
+
+the generated query files are only used internally by zero client/server setup.
+
+### types
+
+you can import types from this folder, but prefer re-exporting from \`../types.ts\`:
+
+\`\`\`ts
+// ❌ okay but not preferred
+import type { Message } from '~/data/generated/types'
+
+// ✅ better - re-export from types.ts
+import type { Message } from '~/data/types'
+\`\`\`
+
+## regeneration
+
+files are regenerated when you run:
+
+\`\`\`bash
+bun on-zero generate
+\`\`\`
+
+or in watch mode:
+
+\`\`\`bash
+bun on-zero generate --watch
+\`\`\`
+
+## more info
+
+see the [on-zero readme](./node_modules/on-zero/README.md) for full documentation.
+`
+}
+
+function generateGroupedQueriesFile(
+  queries: Array<{ name: string; sourceFile: string }>
+) {
+  const sortedFiles = [...new Set(queries.map((q) => q.sourceFile))].sort()
+
+  const exports = sortedFiles
+    .map((file) => `export * as ${file} from '../queries/${file}'`)
+    .join('\n')
+
+  return `/**
+ * auto-generated by: on-zero generate
+ *
+ * grouped query re-exports for minification-safe query identity.
+ * this file re-exports all query modules - while this breaks tree-shaking,
+ * queries are typically small and few in number even in larger apps.
+ */
+${exports}
+`
+}
+
+function generateSyncedQueriesFile(
+  queries: Array<{
+    name: string
+    params: string
+    valibotCode: string
+    sourceFile: string
+  }>
+) {
+  const queryByFile = new Map<string, typeof queries>()
+  for (const q of queries) {
+    if (!queryByFile.has(q.sourceFile)) {
+      queryByFile.set(q.sourceFile, [])
+    }
+    queryByFile.get(q.sourceFile)!.push(q)
+  }
+
+  const sortedFiles = Array.from(queryByFile.keys()).sort()
+
+  const imports = `// auto-generated by: on-zero generate
+// server-side query definitions with validators
+import { defineQuery, defineQueries } from '@rocicorp/zero'
+import * as v from 'valibot'
+import * as Queries from './groupedQueries'
+`
+
+  const namespaceDefs = sortedFiles
+    .map((file) => {
+      const fileQueries = queryByFile
+        .get(file)!
+        .sort((a, b) => a.name.localeCompare(b.name))
+
+      const queryDefs = fileQueries
+        .map((q) => {
+          const lines = q.valibotCode.split('\n').filter((l) => l.trim())
+          const schemaLineIndex = lines.findIndex((l) =>
+            l.startsWith('export const QueryParams')
+          )
+
+          let validatorDef = ''
+          if (schemaLineIndex !== -1) {
+            const schemaLines: string[] = []
+            let openBraces = 0
+            let started = false
+
+            for (let i = schemaLineIndex; i < lines.length; i++) {
+              const line = lines[i]!
+              const cleaned = started
+                ? line
+                : line.replace('export const QueryParams = ', '')
+              schemaLines.push(cleaned)
+              started = true
+
+              openBraces += (cleaned.match(/\{/g) || []).length
+              openBraces -= (cleaned.match(/\}/g) || []).length
+              openBraces += (cleaned.match(/\(/g) || []).length
+              openBraces -= (cleaned.match(/\)/g) || []).length
+
+              if (openBraces === 0 && schemaLines.length > 0) {
+                break
+              }
+            }
+            validatorDef = schemaLines.join('\n')
+          }
+
+          if (q.params === 'void' || !validatorDef) {
+            return `  ${q.name}: defineQuery(() => Queries.${file}.${q.name}()),`
+          }
+
+          const indentedValidator = validatorDef
+            .split('\n')
+            .map((line, i) => (i === 0 ? line : `    ${line}`))
+            .join('\n')
+
+          return `  ${q.name}: defineQuery(
+    ${indentedValidator},
+    ({ args }) => Queries.${file}.${q.name}(args)
+  ),`
+        })
+        .join('\n')
+
+      return `const ${file} = {\n${queryDefs}\n}`
+    })
+    .join('\n\n')
+
+  const queriesObject = sortedFiles.map((file) => `  ${file},`).join('\n')
+
+  return `${imports}
+${namespaceDefs}
+
+export const queries = defineQueries({
+${queriesObject}
+})
+`
+}
+
+export interface GenerateOptions {
+  /** base data directory */
+  dir: string
+  /** run after generation */
+  after?: string
+  /** suppress output */
+  silent?: boolean
+}
+
+export interface WatchOptions extends GenerateOptions {
+  /** debounce delay in ms */
+  debounce?: number
+}
+
+export interface GenerateResult {
+  filesChanged: number
+  modelCount: number
+  schemaCount: number
+  queryCount: number
+}
+
+export async function generate(options: GenerateOptions): Promise<GenerateResult> {
+  const { dir, after, silent } = options
+  const baseDir = resolve(dir)
+  const modelsDir = resolve(baseDir, 'models')
+  const generatedDir = resolve(baseDir, 'generated')
+  const queriesDir = resolve(baseDir, 'queries')
+
+  if (!existsSync(generatedDir)) {
+    mkdirSync(generatedDir, { recursive: true })
+  }
+
+  loadCache()
+
+  const allModelFiles = readdirSync(modelsDir)
+    .filter((f) => f.endsWith('.ts'))
+    .sort()
+
+  const filesWithSchema = allModelFiles.filter((f) =>
+    readFileSync(resolve(modelsDir, f), 'utf-8').includes('export const schema = table(')
+  )
+
+  const writeResults = [
+    writeFileIfChanged(
+      resolve(generatedDir, 'models.ts'),
+      generateModelsFile(allModelFiles)
+    ),
+    writeFileIfChanged(
+      resolve(generatedDir, 'types.ts'),
+      generateTypesFile(filesWithSchema)
+    ),
+    writeFileIfChanged(
+      resolve(generatedDir, 'tables.ts'),
+      generateTablesFile(filesWithSchema)
+    ),
+    writeFileIfChanged(resolve(generatedDir, 'README.md'), generateReadmeFile()),
+  ]
+
+  let filesChanged = writeResults.filter(Boolean).length
+  let queryCount = 0
+
+  // generate query files if queries directory exists
+  if (existsSync(queriesDir)) {
+    const ts = await import('typescript')
+    const { ModelToValibot } = await import('@sinclair/typebox-codegen/model')
+    const { TypeScriptToModel } = await import('@sinclair/typebox-codegen/typescript')
+
+    const queryFiles = readdirSync(queriesDir).filter((f) => f.endsWith('.ts'))
+
+    const allQueries: Array<{
+      name: string
+      params: string
+      valibotCode: string
+      sourceFile: string
+    }> = []
+
+    for (const file of queryFiles) {
+      const filePath = resolve(queriesDir, file)
+      const fileBaseName = basename(file, '.ts')
+
+      try {
+        const content = readFileSync(filePath, 'utf-8')
+        const sourceFile = ts.createSourceFile(
+          filePath,
+          content,
+          ts.ScriptTarget.Latest,
+          true
+        )
+
+        ts.forEachChild(sourceFile, (node) => {
+          if (ts.isVariableStatement(node)) {
+            const exportModifier = node.modifiers?.find(
+              (m) => m.kind === ts.SyntaxKind.ExportKeyword
+            )
+            if (!exportModifier) return
+
+            const declaration = node.declarationList.declarations[0]
+            if (!declaration || !ts.isVariableDeclaration(declaration)) return
+
+            const name = declaration.name.getText(sourceFile)
+            if (name === 'permission') return
+
+            if (declaration.initializer && ts.isArrowFunction(declaration.initializer)) {
+              const params = declaration.initializer.parameters
+              let paramType = 'void'
+
+              if (params.length > 0) {
+                const param = params[0]!
+                paramType = param.type?.getText(sourceFile) || 'unknown'
+              }
+
+              try {
+                const typeString = `type QueryParams = ${paramType}`
+                const model = TypeScriptToModel.Generate(typeString)
+                const valibotCode = ModelToValibot.Generate(model)
+
+                allQueries.push({
+                  name,
+                  params: paramType,
+                  valibotCode,
+                  sourceFile: fileBaseName,
+                })
+              } catch (err) {
+                if (!silent) console.error(`✗ ${name}: ${err}`)
+              }
+            }
+          }
+        })
+      } catch (err) {
+        if (!silent) console.error(`Error processing ${file}:`, err)
+      }
+    }
+
+    queryCount = allQueries.length
+
+    const groupedChanged = writeFileIfChanged(
+      resolve(generatedDir, 'groupedQueries.ts'),
+      generateGroupedQueriesFile(allQueries)
+    )
+    const syncedChanged = writeFileIfChanged(
+      resolve(generatedDir, 'syncedQueries.ts'),
+      generateSyncedQueriesFile(allQueries)
+    )
+
+    if (groupedChanged) filesChanged++
+    if (syncedChanged) filesChanged++
+  }
+
+  if (filesChanged > 0 && !silent) {
+    console.info(
+      `✓ ${allModelFiles.length} models (${filesWithSchema.length} schemas)${queryCount ? `, ${queryCount} queries` : ''}`
+    )
+  }
+
+  // run after command
+  if (filesChanged > 0 && after) {
+    const { execSync } = await import('node:child_process')
+    try {
+      execSync(after, {
+        stdio: 'inherit',
+        env: { ...process.env, ON_ZERO_GENERATED_DIR: generatedDir },
+      })
+    } catch (err) {
+      if (!silent) console.error(`Error running after command: ${err}`)
+    }
+  }
+
+  saveCache()
+
+  return {
+    filesChanged,
+    modelCount: allModelFiles.length,
+    schemaCount: filesWithSchema.length,
+    queryCount,
+  }
+}
+
+export async function watch(options: WatchOptions) {
+  const { dir, debounce = 1000 } = options
+  const baseDir = resolve(dir)
+  const modelsDir = resolve(baseDir, 'models')
+  const queriesDir = resolve(baseDir, 'queries')
+  const generatedDir = resolve(baseDir, 'generated')
+
+  // initial run (silent)
+  await generate({ ...options, silent: true })
+  console.info('👀 watching...\n')
+
+  const chokidar = await import('chokidar')
+
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+  const debouncedRegenerate = (path: string, event: string) => {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    console.info(`\n${event} ${path}`)
+    debounceTimer = setTimeout(() => {
+      generate({ ...options, silent: false })
+    }, debounce)
+  }
+
+  const watcher = chokidar.watch([modelsDir, queriesDir], {
+    persistent: true,
+    ignoreInitial: true,
+    ignored: [generatedDir],
+  })
+
+  watcher.on('change', (path) => debouncedRegenerate(path, '📝'))
+  watcher.on('add', (path) => debouncedRegenerate(path, '➕'))
+  watcher.on('unlink', (path) => debouncedRegenerate(path, '🗑️ '))
+
+  return watcher
+}

package/src/helpers/createMutators.ts

@@ -159,17 +159,23 @@ export function createMutators<Models extends GenericModels>({
 
     for (const [moduleName, moduleExports] of Object.entries(modules)) {
       result[moduleName] = {}
-      for (const [name, exportValue] of Object.entries(moduleExports)) {
-        if (typeof exportValue === 'function') {
-          const fullName = `${moduleName}.${name}`
-          result[moduleName][name] = withDevelopmentLogging(
+      for (const [name] of Object.entries(moduleExports)) {
+        const fullName = `${moduleName}.${name}`
+        // look up function dynamically to support HMR
+        // modules[moduleName] is a proxy that returns updated implementations
+        const getDynamicFn = () => modules[moduleName][name]
+
+        result[moduleName][name] = withDevelopmentLogging(
+          fullName,
+          withTimeoutGuard(
             fullName,
-            withTimeoutGuard(
-              fullName,
-              withValidation(moduleName, name, withContext(exportValue))
+            withValidation(
+              moduleName,
+              name,
+              withContext((...args: any[]) => getDynamicFn()(...args))
             )
           )
-        }
+        )
       }
     }
 

package/src/mutations.ts

@@ -10,6 +10,59 @@ import type {
 } from './types'
 import type { TableBuilderWithColumns } from '@rocicorp/zero'
 
+// HMR registry - stores mutation implementations and proxies by table name
+// allows hot-swapping implementations without changing object references
+// stored on globalThis to persist across HMR module reloads
+const registryKey = '__onZeroMutationRegistry__'
+const proxyKey = '__onZeroProxyRegistry__'
+
+// @ts-ignore
+const mutationRegistry: Map<string, Record<string, Function>> = globalThis[registryKey] ||
+(globalThis[registryKey] = new Map())
+// @ts-ignore
+const proxyRegistry: Map<string, any> =
+  globalThis[proxyKey] || (globalThis[proxyKey] = new Map())
+
+// get or create a proxy that delegates to the registry
+// returns the SAME proxy object on subsequent calls so HMR works
+function getOrCreateMutationProxy<T extends Record<string, Function>>(
+  tableName: string,
+  implementations: T
+): T {
+  // always update implementations (supports HMR)
+  mutationRegistry.set(tableName, implementations)
+
+  // return existing proxy if we have one (HMR case)
+  const existing = proxyRegistry.get(tableName)
+  if (existing) {
+    return existing as T
+  }
+
+  // first time - create the proxy
+  const proxy = new Proxy({} as T, {
+    get(_, key: string) {
+      return mutationRegistry.get(tableName)?.[key]
+    },
+    ownKeys() {
+      const current = mutationRegistry.get(tableName)
+      return current ? Object.keys(current) : []
+    },
+    getOwnPropertyDescriptor(_, key: string) {
+      const current = mutationRegistry.get(tableName)
+      if (current && key in current) {
+        return { enumerable: true, configurable: true, value: current[key] }
+      }
+    },
+    has(_, key: string) {
+      const current = mutationRegistry.get(tableName)
+      return current ? key in current : false
+    },
+  })
+
+  proxyRegistry.set(tableName, proxy)
+  return proxy
+}
+
 // two ways to use it:
 //  - mutations({}) which doesn't add the "allowed" helper or add CRUD
 //  - mutation('tableName', permissions) adds CRUD with permissions, adds allowed
@@ -122,16 +175,16 @@ export function mutations<
       upsert: createCRUDMutation('upsert'),
     }
 
-    const finalMutations = Object.freeze({
+    const finalMutations = {
       ...mutations,
       // overwrite regular mutations but call them if they are defined by user
       ...crudMutations,
-      // expose permissions for usePermission hook
-    }) as any as Mutations
+    } as any as Mutations
 
     setMutationsPermissions(tableName, permissions)
 
-    return finalMutations
+    // return proxy for HMR support - allows swapping implementations at runtime
+    return getOrCreateMutationProxy(tableName, finalMutations)
   }
 
   // no schema/permissions don't add CRUD

package/src/vite-plugin.ts

@@ -0,0 +1,110 @@
+import { isAbsolute, relative, resolve } from 'node:path'
+
+import { generate, type GenerateOptions } from './generate'
+
+import type { Plugin } from 'vite'
+
+export interface OnZeroPluginOptions extends Omit<GenerateOptions, 'dir' | 'silent'> {
+  /** base data directory. defaults to src/data */
+  dir?: string
+  /** additional paths to apply HMR fix to */
+  hmrInclude?: string[]
+  /** disable code generation (HMR only) */
+  disableGenerate?: boolean
+}
+
+function createOnZeroHmrPlugin(hmrInclude: string[] = []): Plugin {
+  const hmrPaths = ['/models/', '/generated/', '/queries/', ...hmrInclude]
+
+  return {
+    name: 'on-zero:hmr',
+    apply: 'serve',
+    enforce: 'post',
+
+    transform(code, id) {
+      if (!hmrPaths.some((p) => id.includes(p)) || !/\.tsx?$/.test(id)) return
+      if (!code.includes('import.meta.hot.invalidate')) return
+
+      return {
+        code: code.replace(
+          /if\s*\(invalidateMessage\)\s*import\.meta\.hot\.invalidate\(invalidateMessage\);?/g,
+          '/* on-zero: HMR invalidate disabled */'
+        ),
+        map: null,
+      }
+    },
+  }
+}
+
+function isWithinDirectory(file: string, dir: string): boolean {
+  const rel = relative(dir, file)
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
+}
+
+export function onZeroPlugin(options: OnZeroPluginOptions = {}): Plugin[] {
+  const dir = options.dir ?? 'src/data'
+
+  let dataDir: string
+  let modelsDir: string
+  let queriesDir: string
+
+  const runGenerate = (silent: boolean) =>
+    generate({
+      dir: dataDir,
+      after: options.after,
+      silent,
+    })
+
+  return [
+    {
+      name: 'on-zero:serve',
+      apply: 'serve',
+
+      configResolved(config) {
+        dataDir = resolve(config.root, dir)
+        modelsDir = resolve(dataDir, 'models')
+        queriesDir = resolve(dataDir, 'queries')
+      },
+
+      async buildStart() {
+        if (!options.disableGenerate) await runGenerate(false)
+      },
+
+      configureServer(server) {
+        if (options.disableGenerate) return
+
+        const handler = async (file: string) => {
+          if (!/\.tsx?$/.test(file)) return
+          if (isWithinDirectory(file, modelsDir) || isWithinDirectory(file, queriesDir)) {
+            await runGenerate(false)
+          }
+        }
+
+        server.watcher.on('change', handler)
+        server.watcher.on('add', handler)
+        server.watcher.on('unlink', handler)
+      },
+    },
+
+    {
+      name: 'on-zero:build',
+      apply: 'build',
+
+      configResolved(config) {
+        dataDir = resolve(config.root, dir)
+      },
+
+      async buildStart() {
+        if (!options.disableGenerate) await runGenerate(true)
+      },
+    },
+
+    createOnZeroHmrPlugin(options.hmrInclude),
+  ]
+}
+
+export const onZeroHmrPlugin = (options?: { include?: string[] }): Plugin => {
+  return createOnZeroHmrPlugin(options?.include)
+}
+
+export default onZeroPlugin