on-zero 0.0.1

package/src/helpers/useZeroDebug.ts

@@ -0,0 +1,102 @@
+import { getCurrentComponentStack } from '@take-out/helpers'
+import { useEffect, useId } from 'react'
+
+import { prettyFormatZeroQuery } from './prettyFormatZeroQuery'
+
+import type { Query } from '@rocicorp/zero'
+
+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) => {
+  const astObject = query['_completeAst']?.() ?? query['ast']
+  const table = astObject?.table ?? 'unknown'
+  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/index.ts

@@ -0,0 +1,18 @@
+export * from './createPermissions'
+export * from './queryRegistry'
+export * from './helpers/batchQuery'
+export * from './helpers/createMutators'
+export * from './helpers/ensureLoggedIn'
+export * from './helpers/mutatorContext'
+
+export * from './createZeroClient'
+export * from './createUseQuery'
+export * from './resolveQuery'
+export { run } from './run'
+export { setRunner, type ZeroRunner } from './zeroRunner'
+export * from './mutations'
+export * from './where'
+export * from './serverWhere'
+export * from './zql'
+
+export type * from './types'

package/src/mutations.ts

@@ -0,0 +1,133 @@
+import { getDidRunPermissionCheck } from './helpers/didRunPermissionCheck'
+
+import type {
+  MutatorContext,
+  TableInsertRow,
+  TableName,
+  TableUpdateRow,
+  Where,
+} from './types'
+import type { TableBuilderWithColumns } from '@rocicorp/zero'
+
+// 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<Mutations extends MutationBuilders>(
+  mutations: Mutations
+): Mutations
+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>
+// 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 as TableName
+
+    const createCRUDMutation = (action: CRUDNames) => {
+      return async (ctx: MutatorContext, obj: any) => {
+        /**
+         * CRUD mutations have permissions handled automatically using `can`:
+         *   - `can` throws an error if it fails
+         *     - zero catches error and rolls back transaction
+         *     - zero returns error to client when you await zero.mutate.x.z().server
+         *   - for INSERT: check runs after insert completes
+         *   - for the rest: check runs before mutation
+         */
+        const runServerPermissionCheck = async () => {
+          if (getDidRunPermissionCheck(ctx)) {
+            // 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, obj)
+          }
+        }
+
+        if (action !== 'insert') {
+          await runServerPermissionCheck()
+        }
+
+        // if user defines insert run theirs, if not run plain zero:
+        const existing = mutations?.[action]
+
+        if (existing) {
+          await existing(ctx, obj)
+        } else {
+          type TableName = keyof typeof ctx.tx.mutate // weird type foo because we declare this module and then type check
+          await ctx.tx.mutate[tableName as TableName]![action](obj)
+        }
+
+        if (action === 'insert') {
+          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
+}

package/src/queryRegistry.ts

@@ -0,0 +1,12 @@
+// registry for query functions to their stable names
+// this allows minification while preserving query identity
+
+const queryNameRegistry = new WeakMap<Function, string>()
+
+export function registerQuery(fn: Function, name: string) {
+  queryNameRegistry.set(fn, name)
+}
+
+export function getQueryName(fn: Function): string | undefined {
+  return queryNameRegistry.get(fn)
+}

package/src/resolveQuery.ts

@@ -0,0 +1,44 @@
+import { getQueryName } from './queryRegistry'
+
+import type { AnyQueryRegistry, Query, Schema as ZeroSchema } from '@rocicorp/zero'
+
+export type PlainQueryFn<
+  TArg = any,
+  TReturn extends Query<any, any, any> = Query<any, any, any>,
+> = (args: TArg) => TReturn
+
+/**
+ * resolves a plain query function to a QueryRequest using the customQueries registry
+ */
+export function resolveQuery<Schema extends ZeroSchema>({
+  customQueries,
+  fn,
+  params,
+}: {
+  customQueries: AnyQueryRegistry
+  fn: PlainQueryFn<any, Query<any, Schema, any>>
+  params?: any
+}) {
+  const queryName = getQueryName(fn)
+  if (!queryName) {
+    const fnName = fn?.name || 'anonymous'
+    throw new Error(
+      `Query function '${fnName}' not registered. ` +
+        `Ensure it is exported from a queries file and passed to createZeroClient via groupedQueries.`
+    )
+  }
+
+  // look up the CustomQuery from the shared registry
+  // queryName is "namespace.name" format, e.g., "user.userById"
+  const [namespace, name] = queryName.split('.', 2)
+  const customQuery = (customQueries as any)[namespace]?.[name]
+
+  if (!customQuery) {
+    throw new Error(
+      `CustomQuery '${queryName}' not found. ` +
+        `Check that the query is exported and the namespace/name matches.`
+    )
+  }
+
+  return params !== undefined ? customQuery(params) : customQuery()
+}

package/src/run.ts

@@ -0,0 +1,62 @@
+import { resolveQuery, type PlainQueryFn } from './resolveQuery'
+import { getRunner, type RunOptions } from './zeroRunner'
+
+import type {
+  AnyQueryRegistry,
+  HumanReadable,
+  Query,
+  Schema as ZeroSchema,
+} from '@rocicorp/zero'
+
+let customQueriesRef: AnyQueryRegistry | null = null
+
+export function setCustomQueries(queries: AnyQueryRegistry) {
+  customQueriesRef = queries
+}
+
+function getCustomQueries(): AnyQueryRegistry {
+  if (!customQueriesRef) {
+    throw new Error(
+      'Custom queries not initialized. Ensure createZeroClient or createZeroServer has been called.'
+    )
+  }
+  return customQueriesRef
+}
+
+// run a query once and return results (non-reactive)
+export function run<
+  Schema extends ZeroSchema,
+  TArg,
+  TTable extends keyof Schema['tables'] & string,
+  TReturn,
+>(
+  fn: PlainQueryFn<TArg, Query<TTable, Schema, TReturn>>,
+  params: TArg,
+  options?: RunOptions
+): Promise<HumanReadable<TReturn>>
+
+export function run<
+  Schema extends ZeroSchema,
+  TTable extends keyof Schema['tables'] & string,
+  TReturn,
+>(
+  fn: PlainQueryFn<void, Query<TTable, Schema, TReturn>>,
+  options?: RunOptions
+): Promise<HumanReadable<TReturn>>
+
+export function run(
+  fnArg: any,
+  paramsOrOptions?: any,
+  optionsArg?: RunOptions
+): Promise<any> {
+  const hasParams =
+    optionsArg !== undefined || (paramsOrOptions && !('type' in paramsOrOptions))
+  const params = hasParams ? paramsOrOptions : undefined
+  const options = hasParams ? optionsArg : paramsOrOptions
+
+  const customQueries = getCustomQueries()
+  const queryRequest = resolveQuery({ customQueries, fn: fnArg, params })
+  const runner = getRunner()
+
+  return runner(queryRequest as any, options)
+}

package/src/server.ts

@@ -0,0 +1 @@
+export * from './createZeroServer'

package/src/serverWhere.ts

@@ -0,0 +1,21 @@
+import { where } from './where'
+
+import type { TableName, Where } from './types'
+import type { Condition } from '@rocicorp/zero'
+
+export function serverWhere<Table extends TableName, Builder extends Where<Table>>(
+  tableName: Table,
+  builder: Builder
+): Where<Table, Condition>
+
+export function serverWhere<
+  Table extends TableName,
+  Builder extends Where = Where<Table>,
+>(builder: Builder): Where<Table, Condition>
+
+export function serverWhere<Table extends TableName, Builder extends Where<Table>>(
+  a: Table | Builder,
+  b?: Builder
+): Where<Table, any> | Builder {
+  return where(a as any, b as any, true)
+}

package/src/state.ts

@@ -0,0 +1,32 @@
+import { createBuilder, type Schema } from '@rocicorp/zero'
+
+import type { AuthData, QueryBuilder } from './types'
+
+let schema: Schema | null = null
+let zql: QueryBuilder | null = null
+let authData: AuthData | null | undefined
+
+const errMessage = `Haven't called createZeroClient or createZeroServer yet!`
+
+export const getZQL = () => {
+  if (!zql) throw new Error(errMessage)
+  return zql
+}
+
+export const getSchema = () => {
+  if (!schema) throw new Error(errMessage)
+  return schema
+}
+
+export const setSchema = (_: Schema) => {
+  schema = _
+  zql = createBuilder(_) as QueryBuilder
+}
+
+export const getAuthData = () => {
+  return authData || null
+}
+
+export const setAuthData = (_: AuthData) => {
+  authData = _
+}

package/src/types.ts

@@ -0,0 +1,136 @@
+import type {
+  Condition,
+  ExpressionBuilder,
+  Row,
+  SchemaQuery,
+  TableBuilderWithColumns,
+  Schema as ZeroSchema,
+  Transaction as ZeroTransaction,
+} from '@rocicorp/zero'
+import type { NullToOptional, TupleToUnion } from '@take-out/helpers'
+
+/**
+ * ➗0️⃣ START OVERRIDDEN TYPES
+ *
+ * To get types, put the following in a .ts file that's included by your tsconfig:
+ *
+ *   export type Schema = typeof schema
+ *
+ *   declare module 'on-zero' {
+ *     interface Config {
+ *       schema: Schema
+ *       authData: AuthData
+ *     }
+ *   }
+ *
+ * on-zero is overridden by consumers of this library to get types which is
+ * needed to allow co-locating certain typed helpers like where() and
+ * mutations() alongside table() because table is later used to create the Zero
+ * schema, which is then needed for where/mutations
+ */
+
+export interface Config {}
+
+interface DefaultConfig {
+  schema: ZeroSchema
+  authData: {}
+  serverActions: null
+}
+
+interface FinalConfig extends Omit<DefaultConfig, keyof Config>, Config {}
+
+export type Schema = FinalConfig['schema']
+
+export type TableName = keyof Schema['tables'] extends string
+  ? keyof Schema['tables']
+  : string
+
+export type Transaction = ZeroTransaction<Schema>
+
+export type AuthData =
+  FinalConfig['authData'] extends Record<string, unknown>
+    ? FinalConfig['authData']
+    : Record<string, unknown>
+
+export type ServerActions =
+  FinalConfig['serverActions'] extends Record<string, unknown>
+    ? FinalConfig['serverActions']
+    : Record<string, unknown>
+
+export type QueryBuilder = SchemaQuery<Schema>
+
+/**
+ * ➗0️⃣ END OVERRIDDEN TYPES
+ */
+
+// the first argument passed to every mutation:
+export type MutatorContext = {
+  tx: Transaction
+  authData: AuthData | null
+  environment: 'server' | 'client'
+  server?: {
+    actions: ServerActions
+    asyncTasks: Array<() => Promise<void>>
+  }
+  can: Can
+}
+
+// turns our mutators with custom context into zero mutators
+export type GetZeroMutators<Models extends GenericModels> = {
+  [Key in keyof Models]: TransformMutators<GetModelMutators<Models>[Key]>
+}
+
+type GetModelMutators<Models extends GenericModels> = {
+  [Key in keyof Models]: Models[Key]['mutate']
+}
+
+export type GenericModels = {
+  [key: string]: {
+    mutate: Record<string, (ctx: MutatorContext, obj?: any) => Promise<any>>
+    permissions?: Where<any, Condition | boolean>
+  }
+}
+
+export type TransformMutators<T> = {
+  [K in keyof T]: T[K] extends (ctx: MutatorContext, ...args: infer Args) => infer Return
+    ? (tx: Transaction, ...args: Args) => Return extends unknown ? Promise<any> : Return
+    : never
+}
+
+export type Where<
+  Table extends TableName = TableName,
+  ReturnType extends Condition | boolean = Condition | boolean,
+> = (
+  expressionBuilder: ExpressionBuilder<Table, Schema>,
+  auth?: AuthData | null
+) => ReturnType
+
+export type Can = <PWhere extends Where>(
+  where: PWhere,
+  obj: string | Record<string, unknown>
+) => Promise<void>
+
+export type AsyncAction = () => Promise<void>
+
+type GenericTable = TableBuilderWithColumns<any>
+
+type GetTableSchema<TS extends GenericTable> =
+  TS extends TableBuilderWithColumns<infer S> ? S : never
+
+// all non-optional keys required (but optional can be undefined)
+export type TableInsertRow<TS extends GenericTable> = NullToOptional<
+  Row<GetTableSchema<TS>>
+>
+
+// only primary keys required
+export type TableUpdateRow<TS extends GenericTable> = Pick<
+  Row<GetTableSchema<TS>>,
+  TablePrimaryKeys<TS>
+> &
+  Partial<TableInsertRow<TS>>
+
+export type TablePrimaryKeys<TS extends GenericTable> = TupleToUnion<
+  GetTableSchema<TS>['primaryKey']
+>
+
+export type ZeroEvent = { type: 'error'; message: string }

package/src/where.ts

@@ -0,0 +1,58 @@
+
+import { getQueryOrMutatorAuthData } from './helpers/getQueryOrMutatorAuthData'
+
+import type { Condition, ExpressionBuilder } from '@rocicorp/zero'
+import { isServer } from './constants'
+import type { TableName, Where } from './types'
+
+export function where<Table extends TableName, Builder extends Where<Table>>(
+  tableName: Table,
+  builder: Builder,
+  isServerOnly?: boolean
+): Where<Table, Condition>
+
+export function where<Table extends TableName, Builder extends Where = Where<Table>>(
+  builder: Builder
+): Where<Table, Condition>
+
+export function where<Table extends TableName, Builder extends Where<Table>>(
+  a: Table | Builder,
+  b?: Builder,
+  isServerOnly = false
+): Where<Table, any> | Builder {
+  const whereFn = (b || a) as any
+
+  const wrappedWhereFn = ((
+    a: ExpressionBuilder<any, any>,
+    b = getQueryOrMutatorAuthData()
+  ) => {
+    if (!isServer && isServerOnly) {
+      // on client (web or native) where conditions always pass
+      return a.and()
+    }
+
+    const result = whereFn(a, b)
+    if (typeof result === 'boolean') {
+      if (result) {
+        return a.cmpLit(0, '=', 0)
+      } else {
+        return a.cmpLit(1, '=', 0)
+      }
+    }
+    return result
+  }) as Builder
+
+  if (b) {
+    WhereTableNameMap.set(wrappedWhereFn, a as Table)
+  }
+
+  return wrappedWhereFn
+}
+
+// permissions where:
+
+const WhereTableNameMap = new WeakMap<Where, TableName>()
+
+export function getWhereTableName(where: Where) {
+  return WhereTableNameMap.get(where)
+}

package/src/zeroRunner.ts

@@ -0,0 +1,28 @@
+import type {
+  HumanReadable,
+  Query,
+  RunOptions,
+  Schema as ZeroSchema,
+} from '@rocicorp/zero'
+
+export type { RunOptions }
+
+export type ZeroRunner = <TReturn>(
+  query: Query<any, ZeroSchema, TReturn>,
+  options?: RunOptions
+) => Promise<HumanReadable<TReturn>>
+
+let runner: ZeroRunner | null = null
+
+export function setRunner(r: ZeroRunner) {
+  runner = r
+}
+
+export function getRunner(): ZeroRunner {
+  if (!runner) {
+    throw new Error(
+      'Zero runner not initialized. Ensure ProvideZero is mounted (client) or createZeroServer is called (server).'
+    )
+  }
+  return runner
+}

package/src/zql.ts

@@ -0,0 +1,10 @@
+import { getZQL } from './state'
+
+import type { QueryBuilder } from './types'
+
+export const zql = new Proxy({} as QueryBuilder, {
+  get(_target, prop) {
+    const b = getZQL()
+    return (b as any)[prop]
+  },
+})

package/types/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/types/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/types/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const isServer: boolean;
+export declare const isBrowser: boolean;
+//# sourceMappingURL=constants.d.ts.map

package/types/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,QAAQ,SAAgC,CAAA;AACrD,eAAO,MAAM,SAAS,SAAY,CAAA"}

package/types/constants.native.d.ts

@@ -0,0 +1,3 @@
+export declare const isServer = false;
+export declare const isBrowser = false;
+//# sourceMappingURL=constants.native.d.ts.map