over-zero 0.0.0

package/src/helpers/clearZeroDatabase.ts

@@ -0,0 +1,68 @@
+import { showToast } from '~/interface/toast/Toast'
+import { zero } from '../zero'
+
+export const clearZeroDatabase = async () => {
+  try {
+    // Get all IndexedDB databases
+    const databases = await indexedDB.databases()
+
+    // Find Zero/Replicache databases
+    const zeroAndReplicacheDatabases = databases.filter((db) => {
+      if (!db.name) return false
+      const name = db.name.toLowerCase()
+      return (
+        name.includes('zero') ||
+        name.includes('replicache') ||
+        name.includes('roc') || // rocicorp prefix
+        name.startsWith('rep:') // replicache prefix
+      )
+    })
+
+    if (zeroAndReplicacheDatabases.length > 0) {
+      // Delete all Zero/Replicache databases
+      await Promise.all(
+        zeroAndReplicacheDatabases.map((db) => {
+          return new Promise<void>((resolve, reject) => {
+            const deleteReq = indexedDB.deleteDatabase(db.name!)
+            deleteReq.onsuccess = () => resolve()
+            deleteReq.onerror = () => reject(deleteReq.error)
+            deleteReq.onblocked = () => reject(new Error('database deletion blocked'))
+          })
+        })
+      )
+
+      const dbNames = zeroAndReplicacheDatabases.map((db) => db.name).join(', ')
+      showToast(
+        `Cleared ${zeroAndReplicacheDatabases.length} Zero/Replicache databases: ${dbNames}`
+      )
+    } else {
+      // Fallback: clear all IndexedDB databases
+      await Promise.all(
+        databases.map((db) => {
+          if (db.name) {
+            return new Promise<void>((resolve, reject) => {
+              const deleteReq = indexedDB.deleteDatabase(db.name!)
+              deleteReq.onsuccess = () => resolve()
+              deleteReq.onerror = () => reject(deleteReq.error)
+              deleteReq.onblocked = () => reject(new Error('database deletion blocked'))
+            })
+          }
+        })
+      )
+      showToast('Cleared all IndexedDB databases')
+    }
+
+    // Close the zero connection before reloading
+    if (zero && typeof (zero as any).close === 'function') {
+      await (zero as any).close()
+    }
+
+    // Reload the page to reinitialize Zero
+    setTimeout(() => {
+      window.location.reload()
+    }, 1000)
+  } catch (error) {
+    console.error('Error clearing Zero database:', error)
+    showToast('Error clearing Zero database')
+  }
+}

package/src/helpers/context.ts

@@ -0,0 +1,28 @@
+import { createAsyncContext } from '@vxrn/helpers'
+import type { MutatorContext } from '../types'
+
+// TODO likely should be called "DataContext" or "ZeroContext" as its useful for permissions outside mutators
+
+const asyncContext = createAsyncContext<MutatorContext>()
+
+// TODO probably rename mutatorContext()
+
+export function context(): MutatorContext {
+  const currentContext = asyncContext.get()
+  if (!currentContext) {
+    throw new Error('context must be called within a mutator')
+  }
+
+  return currentContext
+}
+
+export function isInZeroMutation() {
+  return !!asyncContext.get()
+}
+
+export function runWithContext<T>(
+  context: MutatorContext,
+  fn: () => T | Promise<T>
+): Promise<T> {
+  return asyncContext.run(context, fn)
+}

package/src/helpers/createMutators.ts

@@ -0,0 +1,139 @@
+import { isClient, isServer, mapObject, time } from '@vxrn/helpers'
+import type { AuthData } from 'start/types'
+import type { GenericTransaction, MutatorContext } from '../types'
+import { runWithContext } from './context'
+
+type MutatorProps = {
+  environment: 'server' | 'client'
+  authData: AuthData | null
+  can: (where: string, action: () => Promise<any>, obj: any) => void
+  models: any
+  asyncTasks?: Array<() => Promise<void>>
+  createServerActions?: (authData: AuthData | null) => Record<string, any>
+}
+
+type TransformMutators<T> = {
+  [K in keyof T]: T[K] extends (ctx: MutatorContext, ...args: infer Args) => infer Return
+    ? (tx: GenericTransaction, ...args: Args) => Return
+    : never
+}
+
+export function createMutators<
+  MutatorsIn extends Record<string, any>,
+  Mutators extends {
+    [K in keyof MutatorsIn]: TransformMutators<MutatorsIn[K]>
+  },
+>({
+  environment,
+  authData,
+  createServerActions,
+  asyncTasks = [],
+  can,
+  models,
+}: MutatorProps) {
+  const serverActions = createServerActions?.(authData)
+
+  const modelMutators = mapObject(models, (val) => val.mutate) as {
+    [K in keyof typeof models]: (typeof models)[K]['mutate']
+  }
+
+  function withContext<Args extends any[]>(fn: (...args: Args) => Promise<void>) {
+    return async (tx: GenericTransaction, ...args: Args): Promise<void> => {
+      const mutationContext = {
+        tx,
+        authData,
+        environment,
+        can,
+        serverActions,
+        asyncTasks,
+      }
+
+      return await runWithContext(mutationContext, () => {
+        // @ts-expect-error type shenanigan
+        // map to our mutations() helper
+        return fn(mutationContext, ...args)
+      })
+    }
+  }
+
+  function withDevelopmentLogging<Args extends any[]>(
+    name: string,
+    fn: (...args: Args) => Promise<void>
+  ) {
+    if (process.env.NODE_ENV !== 'development' && !process.env.IS_TESTING) {
+      return fn
+    }
+
+    return async (...args: Args): Promise<void> => {
+      const startTime = performance.now()
+
+      try {
+        if (isServer) {
+          console.info(`[mutator] ${name} start`)
+        }
+        const result = await fn(...args)
+        const duration = (performance.now() - startTime).toFixed(2)
+        if (isClient) {
+          console.groupCollapsed(`[mutator] ${name} completed in ${duration}ms`)
+          console.info('→', args[1])
+          console.info('←', result)
+          console.trace()
+          console.groupEnd()
+        } else {
+          // TODO in prod just track
+          console.info(`[mutator] ${name} completed in ${duration}ms`)
+        }
+        return result
+      } catch (error) {
+        const duration = (performance.now() - startTime).toFixed(2)
+        console.groupCollapsed(`[mutator] ${name} failed after ${duration}ms`)
+        console.error('error:', error)
+        console.info('arguments:', JSON.stringify(args[1], null, 2))
+        console.info('stack trace:', new Error().stack)
+        console.groupEnd()
+        throw error
+      }
+    }
+  }
+
+  function withTimeoutGuard<Args extends any[]>(
+    name: string,
+    fn: (...args: Args) => Promise<void>,
+    // don't want this too high - zero runs mutations in order and waits for the last to finish it seems
+    // so if one mutation gets stuck it will just sit there
+    timeoutMs: number = time.ms.minutes(1)
+  ) {
+    return async (...args: Args): Promise<void> => {
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`[mutator] ${name} timeout after ${timeoutMs}ms`))
+        }, timeoutMs)
+      })
+
+      return Promise.race([fn(...args), timeoutPromise])
+    }
+  }
+
+  function decorateMutators<T extends Record<string, Record<string, any>>>(
+    modules: T
+  ): Mutators {
+    const result: any = {}
+
+    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(
+            fullName,
+            withTimeoutGuard(fullName, withContext(exportValue))
+          )
+        }
+      }
+    }
+
+    return result
+  }
+
+  return decorateMutators(modelMutators)
+}

package/src/helpers/ensureLoggedIn.ts

@@ -0,0 +1,8 @@
+import { ensure } from '@vxrn/helpers'
+import { context } from './context'
+
+export const ensureLoggedIn = () => {
+  const { authData } = context()
+  ensure(authData, 'logged in')
+  return authData
+}

package/src/helpers/getAuthData.tsx

@@ -0,0 +1,12 @@
+// import { getAuth } from '~/auth/client/authClient'
+
+// export const getAuthData = () => {
+//   const { user } = getAuth()
+//   return user
+//     ? {
+//         id: user.id || 'anon',
+//         email: user.email,
+//         role: undefined,
+//       }
+//     : null
+// }

package/src/helpers/prettyFormatZeroQuery.ts

@@ -0,0 +1,167 @@
+import type { Query } from '@rocicorp/zero'
+import { ellipsis } from '@vxrn/helpers'
+
+export const prettyFormatZeroQuery = (
+  query: Query<any, any, any>,
+  mode: 'full' | 'minimal' = 'full'
+): string => {
+  // @ts-expect-error accessing hidden property
+  const astObject = query['_completeAst']?.()
+
+  if (!astObject) return ''
+
+  if (mode === 'minimal') {
+    return prettyFormatMinimal(astObject)
+  }
+  return prettyFormatFull(astObject)
+}
+
+const prettyFormatFull = (astObject: any, indent = 0): string => {
+  if (!astObject || !astObject.table) return ''
+
+  const spaces = '  '.repeat(indent)
+  let query = astObject.table
+  let hasChainedMethods = false
+
+  // Add where conditions
+  if (astObject.where) {
+    const whereClause = formatWhere(astObject.where)
+    if (hasChainedMethods) {
+      query += `\n${spaces}  ${whereClause}`
+    } else {
+      query += whereClause
+      hasChainedMethods = true
+    }
+  }
+
+  // Add limit
+  if (astObject.limit) {
+    const limitClause = `.limit(${astObject.limit})`
+    if (hasChainedMethods) {
+      query += `\n${spaces}  ${limitClause}`
+    } else {
+      query += limitClause
+      hasChainedMethods = true
+    }
+  }
+
+  // Add orderBy
+  if (astObject.orderBy && astObject.orderBy.length > 0) {
+    const orderClauses = astObject.orderBy
+      .map(([field, direction]: [string, string]) => `${field}, ${direction}`)
+      .join(', ')
+    const orderByClause = `.orderBy(${orderClauses})`
+    if (hasChainedMethods) {
+      query += `\n${spaces}  ${orderByClause}`
+    } else {
+      query += orderByClause
+      hasChainedMethods = true
+    }
+  }
+
+  // Add related queries
+  if (astObject.related && astObject.related.length > 0) {
+    astObject.related.forEach((rel: any) => {
+      if (rel.subquery) {
+        const alias = rel.subquery.alias || rel.subquery.table
+        const subQuery = prettyFormatFull(rel.subquery, indent + 1)
+        query += `\n${spaces}  .related(${alias}, q => q.${subQuery}`
+      }
+    })
+
+    // Add closing parentheses
+    const closingParens = ')'.repeat(astObject.related.length)
+    query += `\n${spaces}${closingParens}`
+  }
+
+  return query
+}
+
+const prettyFormatMinimal = (astObject: any): string => {
+  if (!astObject || !astObject.table) return ''
+
+  let query = astObject.table
+
+  // Add where conditions only
+  if (astObject.where) {
+    query += formatWhere(astObject.where).replace('.where(', '(')
+  }
+
+  // Add sub-queries info if present
+  if (astObject.related && astObject.related.length > 0) {
+    const subQueries = collectSubQueryTables(astObject.related)
+    const count = subQueries.length
+    const tableNames = subQueries.join(', ')
+    query += ` (+${count}: ${ellipsis(tableNames, 30)})`
+  }
+
+  return query
+}
+
+const collectSubQueryTables = (related: any[]): string[] => {
+  const tables: string[] = []
+
+  related.forEach((rel: any) => {
+    if (rel.subquery) {
+      const tableName = rel.subquery.alias || rel.subquery.table
+      tables.push(tableName)
+
+      // Recursively collect nested sub-queries
+      if (rel.subquery.related && rel.subquery.related.length > 0) {
+        tables.push(...collectSubQueryTables(rel.subquery.related))
+      }
+    }
+  })
+
+  return tables
+}
+
+const formatWhere = (where: any): string => {
+  if (!where) return ''
+
+  if (where.type === 'simple') {
+    const column = where.left?.name || where.left
+    const value = where.right?.value !== undefined ? where.right.value : where.right
+    const op = where.op || '='
+
+    // Special case: if column is "id" and op is "=" and value is a single item, show just the value
+    if (
+      column === 'id' &&
+      op === '=' &&
+      (typeof value === 'string' || typeof value === 'number')
+    ) {
+      return `(${value})`
+    }
+
+    if (op === '=') {
+      return `.where(${column}, ${value})`
+    }
+    return `.where(${column}, ${op}, ${value})`
+  }
+
+  if (where.type === 'and' && where.conditions) {
+    let result = ''
+    where.conditions.forEach((condition: any, index: number) => {
+      if (index === 0) {
+        result += formatWhere(condition)
+      } else {
+        result += `.and(${formatWhere(condition).slice(1)})` // Remove the leading dot
+      }
+    })
+    return result
+  }
+
+  if (where.type === 'or' && where.conditions) {
+    let result = ''
+    where.conditions.forEach((condition: any, index: number) => {
+      if (index === 0) {
+        result += formatWhere(condition)
+      } else {
+        result += `.or(${formatWhere(condition).slice(1)})` // Remove the leading dot
+      }
+    })
+    return result
+  }
+
+  return ''
+}

package/src/helpers/useAuthData.ts

@@ -0,0 +1,13 @@
+// import { useMemo } from 'react'
+// import { useAuth } from '~/auth/client/authClient'
+// import { getAuthData } from './getAuthData'
+
+// export const useAuthData = () => {
+//   const auth = useAuth()
+//   const userId = auth?.user?.id || 'anon'
+
+//   // biome-ignore lint/correctness/useExhaustiveDependencies: its based on id
+//   return useMemo(() => {
+//     return getAuthData()
+//   }, [userId])
+// }

package/src/helpers/useZeroDebug.ts

@@ -0,0 +1,104 @@
+import type { Query } from '@rocicorp/zero'
+import { getCurrentComponentStack } from '@vxrn/helpers'
+import { useEffect, useId } from 'react'
+import { prettyFormatZeroQuery } from './prettyFormatZeroQuery'
+
+const activeQueries = new Map<string, number>()
+
+// AST change tracking
+interface AstHistory {
+  asts: string[]
+  changeCount: number
+}
+
+const astHistoryByComponent = new Map<string, AstHistory>()
+
+// control what is logged here:
+const filterLogs = (table: string): boolean => false
+
+const COLLAPSED = true
+const AST_CHANGE_THRESHOLD = 4
+const MAX_AST_HISTORY = 10
+
+// short name because otherwise it often forces multiple lines in chrome devtools
+// due to showing the filename next to log lines
+export const useZeroDebug = (query: Query<any, any, any>, options: any, results: any) => {
+  // if (DEBUG_LEVEL < 2) {
+  //   return
+  // }
+
+  const astObject = query['_completeAst']?.()
+  const table = astObject.table
+  const ast = JSON.stringify(astObject, null, 2)
+  const queryDisabled = !options || options?.enabled === false
+  const enabled = !queryDisabled && filterLogs(table)
+  const stack = new Error().stack
+  const isPermissionQuery = stack?.includes(`usePermission.ts`)
+  const id = useId()
+
+  // log here not in effect so we can breakpoint and find the query
+  const num = activeQueries.get(ast) || 0
+  const shouldLog = enabled && num === 0
+  if (enabled) {
+    activeQueries.set(ast, num + 1)
+    if (shouldLog) {
+      if (COLLAPSED) {
+        console.groupCollapsed(
+          `${isPermissionQuery ? `👮‍♂️` : `✨`}${prettyFormatZeroQuery(query, 'minimal')}`
+        )
+        console.info(id, prettyFormatZeroQuery(query, 'full'))
+        console.info('cached result', results)
+        console.trace()
+        console.groupEnd()
+      } else {
+        console.info(`✨`, prettyFormatZeroQuery(query, 'full'))
+      }
+    }
+  }
+
+  // track AST changes per component
+  useEffect(() => {
+    if (!enabled) return
+    const history = astHistoryByComponent.get(id) || { asts: [], changeCount: 0 }
+    const currentAst = ast
+    const lastAst = history.asts[history.asts.length - 1]
+
+    if (currentAst !== lastAst) {
+      history.asts.push(currentAst)
+      if (history.asts.length > MAX_AST_HISTORY) {
+        history.asts.shift()
+      }
+      history.changeCount++
+      astHistoryByComponent.set(id, history)
+
+      if (history.changeCount > AST_CHANGE_THRESHOLD) {
+        console.warn(
+          `⚠️ AST changed ${history.changeCount} times for component.
+        - id: ${id}
+        - stack: ${getCurrentComponentStack('short')}
+        - table: ${table}`,
+          {
+            componentId: id,
+            table,
+            changeCount: history.changeCount,
+            recentAsts: history.asts,
+          }
+        )
+      }
+    }
+  }, [id, ast, table, enabled])
+
+  useEffect(() => {
+    if (!enabled) return
+    return () => {
+      activeQueries.set(ast, activeQueries.get(ast)! - 1)
+    }
+  }, [ast, enabled])
+
+  // cleanup AST history on unmount
+  useEffect(() => {
+    return () => {
+      astHistoryByComponent.delete(id)
+    }
+  }, [id])
+}

package/src/helpers/zeroEmitter.ts

@@ -0,0 +1,5 @@
+import { createEmitter } from '@vxrn/helpers'
+
+export const zeroEmitter = createEmitter<ZeroEvent | undefined>('zero', undefined)
+
+type ZeroEvent = { type: 'error'; message: string }

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './createPermissions'
+export * from './helpers/batchQuery'
+export * from './helpers/context'
+export * from './helpers/createMutators'
+export * from './helpers/ensureLoggedIn'
+
+export * from './mutations'
+export * from './createZeroClient'
+export * from './createZeroServer'
+
+export type * from './types'
+
+// export * from '~/data/schema'
+// export * from './types'
+// export * from '../zero'

package/src/mutations.ts

@@ -0,0 +1,121 @@
+import type { TableBuilderWithColumns } from '@rocicorp/zero'
+import type { MutatorContext, TableInsertRow, TableUpdateRow, Where } from './types'
+
+// 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
+
+type MutationBuilder<Obj = any> = (ctx: MutatorContext, obj?: Obj) => Promise<void>
+type MutationBuilders = Record<string, MutationBuilder>
+
+// start of adding custom can.write(message) style
+
+// type PermissionedMutationBuilder<Permissions extends PermissionsWhere, Obj = any> = (
+//   ctx: MutatorContext & {
+//     can: any
+//   },
+//   obj?: Obj
+// ) => Promise<void>
+// type PermissionedMutationBuilders<Permissions extends PermissionsWhere> = Record<
+//   string,
+//   PermissionedMutationBuilder<Permissions>
+// >
+
+type GenericTable = TableBuilderWithColumns<any>
+
+type CRUDMutations<Table extends GenericTable> = {
+  insert: MutationBuilder<TableInsertRow<Table>>
+  upsert: MutationBuilder<TableInsertRow<Table>>
+  update: MutationBuilder<TableUpdateRow<Table>>
+  delete: MutationBuilder<TableUpdateRow<Table>>
+}
+
+type CRUDNames = 'insert' | 'upsert' | 'update' | 'delete'
+
+type MutationsWithCRUD<Table extends GenericTable, Mutations extends MutationBuilders> = {
+  [Key in CRUDNames | keyof Mutations]: Key extends keyof Mutations
+    ? Mutations[Key]
+    : Key extends keyof CRUDMutations<any>
+      ? CRUDMutations<Table>[Key]
+      : never
+}
+
+export function mutations<Table extends GenericTable, Permissions extends Where>(
+  table: Table,
+  permissions: Permissions
+): MutationsWithCRUD<Table, {}>
+
+export function mutations<
+  Table extends GenericTable,
+  Permissions extends Where,
+  Mutations extends MutationBuilders,
+>(
+  table: Table,
+  permissions: Permissions,
+  mutations: Mutations
+): MutationsWithCRUD<Table, Mutations>
+
+export function mutations<Mutations extends MutationBuilder>(
+  mutations: Mutations
+): Mutations
+
+// TODO we should enforece the CRUD mutations obj to the callier so they get it auto-typed
+export function mutations<
+  Table extends GenericTable,
+  Mutations extends Record<string, MutationBuilder>,
+>(table: Table | Mutations, permissions?: Where, mutations?: Mutations): Mutations {
+  if (permissions) {
+    const tableName = (table as Table).schema.name
+
+    const createCRUDMutation = (action: CRUDNames) => {
+      return async (ctx: MutatorContext, obj: any) => {
+        // run permission query - for delete before the mutation runs, for the rest after
+        // when the "can" query is unsuccessful it throws an error which will revert everything
+        const runServerPermissionCheck = async () => {
+          if (ctx.didCanPermissionsRun) {
+            // if the user-defined CRUD mutation runs their own "can", we avoid running ours
+            return
+          }
+
+          // only validate on the server
+          if (process.env.VITE_ENVIRONMENT === 'ssr') {
+            await ctx.can(permissions, action, obj)
+          }
+        }
+
+        if (action === 'delete') {
+          await runServerPermissionCheck()
+        }
+
+        // if user defines insert run theirs, if not run plain zero:
+        const existing = mutations?.[action]
+
+        if (existing) {
+          await existing(ctx, obj)
+        } else {
+          await ctx.tx.mutate[tableName][action](obj)
+        }
+
+        if (action !== 'delete') {
+          await runServerPermissionCheck()
+        }
+      }
+    }
+
+    const crudMutations: CRUDMutations<any> = {
+      insert: createCRUDMutation('insert'),
+      update: createCRUDMutation('update'),
+      delete: createCRUDMutation('delete'),
+      upsert: createCRUDMutation('upsert'),
+    }
+
+    return {
+      ...mutations,
+      // overwrite regular mutations but call them if they are defined by user
+      ...crudMutations,
+    } as any as Mutations
+  }
+
+  // no schema/permissions don't add CRUD
+  return table as any
+}