lazyconvex 0.0.0

package/src/server/types.ts

@@ -0,0 +1,392 @@
+import type { CustomBuilder } from 'convex-helpers/server/zod4'
+import type {
+  ActionBuilder,
+  FunctionVisibility,
+  GenericDataModel,
+  MutationBuilder,
+  PaginationOptions,
+  paginationOptsValidator,
+  QueryBuilder,
+  RegisteredAction,
+  RegisteredMutation,
+  RegisteredQuery
+} from 'convex/server'
+import type { GenericId } from 'convex/values'
+import type { z as _, ZodNullable, ZodNumber, ZodObject, ZodOptional, ZodRawShape } from 'zod/v4'
+
+interface BaseBuilders {
+  m: Mb
+  q: Qb
+}
+interface CacheBuilders<DM extends GenericDataModel = GenericDataModel> {
+  action: ActionBuilder<DM, 'public'>
+  cm: Mb
+  cq: Qb
+  internalMutation: MutationBuilder<DM, 'internal'>
+  internalQuery: QueryBuilder<DM, 'internal'>
+  mutation: MutationBuilder<DM, 'public'>
+  query: QueryBuilder<DM, 'public'>
+}
+interface CacheOptions<S extends ZodRawShape, K extends keyof _.output<ZodObject<S>> & string> {
+  fetcher?: (c: ActionCtxLike, key: _.output<ZodObject<S>>[K]) => Promise<_.output<ZodObject<S>>>
+  key: K
+  schema: ZodObject<S>
+  table: string
+  ttl?: number
+}
+interface ChildConfig {
+  foreignKey: string
+  index?: string
+  parent: string
+  schema: ZodObject<ZodRawShape>
+}
+interface ComparisonOp<V> {
+  $between?: [V, V]
+  $gt?: V
+  $gte?: V
+  $lt?: V
+  $lte?: V
+}
+interface CrudBuilders extends BaseBuilders {
+  children: Record<string, ChildConfig>
+  cm: Mb
+  cq: Qb
+  pq: Qb
+}
+interface CrudOptions<S extends ZodRawShape> {
+  auth?: { where?: WhereOf<S> }
+  cascade?: boolean
+  pub?: { where?: WhereOf<S> }
+  search?: 'index'
+  softDelete?: boolean
+}
+interface DbCtx {
+  db: DbLike
+}
+interface MutCtx extends UserCtx {
+  storage: StorageLike
+}
+type Rec = Record<string, unknown>
+interface UserCtx extends DbCtx {
+  user: Rec
+}
+const ERROR_MESSAGES = {
+  ALREADY_ORG_MEMBER: 'Already a member of this organization',
+  CANNOT_MODIFY_ADMIN: 'Admins cannot modify other admins',
+  CANNOT_MODIFY_OWNER: 'Cannot modify the owner',
+  CHUNK_ALREADY_UPLOADED: 'Chunk already uploaded',
+  CHUNK_NOT_FOUND: 'Chunk not found',
+  CONFLICT: 'Conflict detected',
+  EDITOR_REQUIRED: 'Editor permission required',
+  FILE_NOT_FOUND: 'File not found',
+  FILE_TOO_LARGE: 'File too large',
+  FORBIDDEN: 'Forbidden',
+  INCOMPLETE_UPLOAD: 'Incomplete upload',
+  INSUFFICIENT_ORG_ROLE: 'Insufficient permissions',
+  INVALID_FILE_TYPE: 'Invalid file type',
+  INVALID_INVITE: 'Invalid invite',
+  INVALID_MESSAGE: 'Invalid message',
+  INVALID_SESSION_STATE: 'Invalid session state',
+  INVALID_TOOL_ARGS: 'Invalid tool arguments',
+  INVALID_WHERE: 'Invalid filters',
+  INVITE_EXPIRED: 'Invite has expired',
+  JOIN_REQUEST_EXISTS: 'Join request already exists',
+  LIMIT_EXCEEDED: 'Limit exceeded',
+  MESSAGE_NOT_SAVED: 'Message not saved',
+  MUST_TRANSFER_OWNERSHIP: 'Must transfer ownership before leaving',
+  NO_FETCHER: 'No fetcher configured',
+  NO_PRECEDING_USER_MESSAGE: 'No preceding user message',
+  NOT_AUTHENTICATED: 'Please log in',
+  NOT_AUTHORIZED: 'Not authorized',
+  NOT_FOUND: 'Not found',
+  NOT_ORG_MEMBER: 'Not a member of this organization',
+  ORG_SLUG_TAKEN: 'Organization slug already taken',
+  RATE_LIMITED: 'Too many requests',
+  SESSION_NOT_FOUND: 'Session not found',
+  TARGET_MUST_BE_ADMIN: 'Can only transfer ownership to an admin',
+  UNAUTHORIZED: 'Unauthorized',
+  USER_NOT_FOUND: 'User not found'
+} as const
+type Ab<V extends FunctionVisibility = 'public'> = CustomBuilder<
+  'action',
+  Record<string, never>,
+  Rec,
+  Record<string, never>,
+  unknown,
+  V,
+  Rec
+>
+interface ActionCtxLike {
+  runMutation: (ref: string, args: Rec) => Promise<unknown>
+  runQuery: (ref: string, args: Rec) => Promise<unknown>
+}
+interface AuthorInfo {
+  [key: string]: unknown
+  email?: string
+  image?: string
+  name?: string
+}
+interface CacheCrudResult<S extends ZodRawShape> {
+  all: RegisteredQuery<'public', Rec, DocBase<S>[]>
+  create: RegisteredMutation<'public', Rec, string>
+  get: RegisteredQuery<'public', Rec, (DocBase<S> & { cacheHit: true }) | null>
+  getInternal: RegisteredQuery<'internal', Rec, DocBase<S> | null>
+  invalidate: RegisteredMutation<'public', Rec, DocBase<S> | null>
+  list: RegisteredQuery<'public', Rec, PaginatedResult<DocBase<S>>>
+  load: RegisteredAction<'public', Rec, _.output<ZodObject<S>> & { cacheHit: boolean }>
+  purge: RegisteredMutation<'public', Rec, number>
+  read: RegisteredQuery<'public', Rec, DocBase<S> | null>
+  refresh: RegisteredAction<'public', Rec, _.output<ZodObject<S>> & { cacheHit: boolean }>
+  rm: RegisteredMutation<'public', Rec, DocBase<S> | null>
+  set: RegisteredMutation<'internal', Rec, void>
+  update: RegisteredMutation<'public', Rec, DocBase<S>>
+}
+interface CanEditOpts {
+  acl: boolean
+  doc: {
+    editors?: string[]
+    userId: string
+  }
+  role: OrgRole
+  userId: string
+}
+interface ChildCrudResult<S extends ZodRawShape> {
+  create: RegisteredMutation<'public', Rec, string>
+  get: RegisteredQuery<'public', Rec, DocBase<S> | null>
+  list: RegisteredQuery<'public', Rec, DocBase<S>[]>
+  rm: RegisteredMutation<'public', Rec, DocBase<S>>
+  update: RegisteredMutation<'public', Rec, DocBase<S> | null>
+}
+interface CrudReadApi<S extends ZodRawShape, V extends FunctionVisibility = 'public'> {
+  all: RegisteredQuery<V, { where?: WhereOf<S> }, EnrichedDoc<S>[]>
+  count: RegisteredQuery<V, { where?: WhereOf<S> }, number>
+  list: RegisteredQuery<V, { paginationOpts: PaginationOptions; where?: WhereOf<S> }, PaginatedResult<EnrichedDoc<S>>>
+  read: RegisteredQuery<V, { id: string; own?: boolean; where?: WhereOf<S> }, EnrichedDoc<S> | null>
+  search: RegisteredQuery<V, { fields?: string[]; query: string; where?: WhereOf<S> }, EnrichedDoc<S>[]>
+}
+interface CrudResult<S extends ZodRawShape> {
+  auth: CrudReadApi<S>
+  authIndexed: RegisteredQuery<
+    'public',
+    { index: string; key: string; value: string; where?: WhereOf<S> },
+    EnrichedDoc<S>[]
+  >
+  bulkRm: RegisteredMutation<'public', { ids: string[] }, number>
+  bulkUpdate: RegisteredMutation<'public', { data: Partial<_.output<ZodObject<S>>>; ids: string[] }, unknown[]>
+  create: RegisteredMutation<'public', _.output<ZodObject<S>>, string>
+  pub: CrudReadApi<S>
+  pubIndexed: RegisteredQuery<
+    'public',
+    { index: string; key: string; value: string; where?: WhereOf<S> },
+    EnrichedDoc<S>[]
+  >
+  restore?: RegisteredMutation<'public', { id: string }, DocBase<S>>
+  rm: RegisteredMutation<'public', { id: string }, DocBase<S>>
+  update: RegisteredMutation<
+    'public',
+    Partial<_.output<ZodObject<S>>> & { expectedUpdatedAt?: number; id: string },
+    DocBase<S>
+  >
+}
+interface DbLike extends DbReadLike {
+  delete: (id: string) => Promise<void>
+  insert: (table: string, data: Rec) => Promise<string>
+  patch: (id: string, data: Rec) => Promise<void>
+  system: DbReadLike
+}
+interface DbReadLike {
+  get: (id: string) => Promise<null | Rec>
+  query: (table: string) => QueryLike
+}
+type DocBase<S extends ZodRawShape> = _.output<ZodObject<S>> & {
+  _creationTime: number
+  _id: string
+  updatedAt: number
+}
+type EnrichedDoc<S extends ZodRawShape> = WithUrls<
+  DocBase<S> & {
+    author: AuthorInfo | null
+    own: boolean | null
+    userId: string
+  }
+>
+type ErrorCode = keyof typeof ERROR_MESSAGES
+type FID = GenericId<'_storage'>
+interface FilterLike {
+  and: (a: unknown, b: unknown) => unknown
+  eq: (a: unknown, b: unknown) => unknown
+  field: (name: string) => unknown
+  gt: (a: unknown, b: unknown) => unknown
+  gte: (a: unknown, b: unknown) => unknown
+  lt: (a: unknown, b: unknown) => unknown
+  lte: (a: unknown, b: unknown) => unknown
+  or: (a: unknown, b: unknown) => unknown
+}
+interface IndexLike {
+  eq: (field: string, value: unknown) => IndexLike
+}
+type Mb<V extends FunctionVisibility = 'public'> = CustomBuilder<
+  'mutation',
+  Record<string, never>,
+  Rec,
+  Record<string, never>,
+  unknown,
+  V,
+  Rec
+>
+interface MutationCtxLike {
+  auth: { getUserIdentity: () => Promise<unknown> }
+  db: DbLike
+  storage: StorageLike
+}
+interface OrgCrudResult<S extends ZodRawShape> {
+  addEditor: RegisteredMutation<'public', Rec, DocBase<S> | null>
+  all: RegisteredQuery<'public', Rec, OrgEnrichedDoc<S>[]>
+  bulkRm: RegisteredMutation<'public', Rec, number>
+  bulkUpdate: RegisteredMutation<'public', Rec, DocBase<S>[]>
+  count: RegisteredQuery<'public', Rec, number>
+  create: RegisteredMutation<'public', Rec, string>
+  editors: RegisteredQuery<'public', Rec, { email: string; name: string; userId: string }[]>
+  list: RegisteredQuery<'public', Rec, PaginatedResult<OrgEnrichedDoc<S>>>
+  read: RegisteredQuery<'public', Rec, OrgEnrichedDoc<S>>
+  removeEditor: RegisteredMutation<'public', Rec, DocBase<S> | null>
+  rm: RegisteredMutation<'public', Rec, DocBase<S>>
+  setEditors: RegisteredMutation<'public', Rec, DocBase<S> | null>
+  update: RegisteredMutation<'public', Rec, DocBase<S> | null>
+}
+type OrgEnrichedDoc<S extends ZodRawShape> = WithUrls<
+  DocBase<S> & {
+    author: AuthorInfo | null
+    orgId: string
+    own: boolean | null
+    userId: string
+  }
+>
+type OrgRole = 'admin' | 'member' | 'owner'
+interface PaginatedResult<D> {
+  continueCursor: string
+  isDone: boolean
+  page: D[]
+}
+type PaginationOptsShape = Record<keyof typeof paginationOptsValidator.fields, ZodNullable | ZodNumber | ZodOptional>
+type Qb<V extends FunctionVisibility = 'public'> = CustomBuilder<
+  'query',
+  Record<string, never>,
+  Rec,
+  Record<string, never>,
+  unknown,
+  V,
+  Rec
+>
+interface QueryCtxLike {
+  auth: { getUserIdentity: () => Promise<unknown> }
+  db: DbLike
+  storage: StorageLike
+}
+interface QueryLike {
+  collect: () => Promise<Rec[]>
+  filter: (fn: (fb: FilterLike) => unknown) => QueryLike
+  first: () => Promise<null | Rec>
+  order: (dir: 'asc' | 'desc') => QueryLike
+  paginate: (opts: Rec) => Promise<{ continueCursor: string; isDone: boolean; page: Rec[] }>
+  take: (n: number) => Promise<Rec[]>
+  unique: () => Promise<null | Rec>
+  withIndex: (name: string, fn?: (ib: IndexLike) => unknown) => QueryLike
+  withSearchIndex: (name: string, fn: (sb: SearchLike) => unknown) => QueryLike
+}
+interface ReadCtx {
+  db: DbLike
+  storage: StorageLike
+  viewerId: null | string
+  withAuthor: <T extends { userId: string }>(
+    docs: T[]
+  ) => Promise<
+    (T & {
+      author: null | Rec
+      own: boolean | null
+    })[]
+  >
+}
+interface SearchLike {
+  search: (field: string, query: string) => unknown
+}
+interface SetupConfig<DM extends GenericDataModel = GenericDataModel> {
+  action: ActionBuilder<DM, 'public'>
+  children?: Record<string, ChildConfig>
+  getAuthUserId: (ctx: never) => Promise<null | string>
+  internalMutation: MutationBuilder<DM, 'internal'>
+  internalQuery: QueryBuilder<DM, 'internal'>
+  mutation: MutationBuilder<DM, 'public'>
+  orgCascadeTables?: string[]
+  orgSchema?: ZodObject<ZodRawShape>
+  query: QueryBuilder<DM, 'public'>
+}
+interface StorageLike {
+  delete: (id: string) => Promise<void>
+  getUrl: (id: string) => Promise<null | string>
+}
+type UrlKey<K, V> =
+  NonNullable<V> extends FID | FID[] | readonly FID[] ? `${K & string}Url${NonNullable<V> extends FID ? '' : 's'}` : never
+type UrlVal<V> =
+  NonNullable<V> extends FID | FID[] | readonly FID[]
+    ? NonNullable<V> extends FID
+      ? null | string
+      : (null | string)[]
+    : never
+type WhereFieldValue<V> = ComparisonOp<V> | V
+type WhereGroupOf<S extends ZodRawShape> = {
+  [K in keyof _.output<ZodObject<S>>]?: WhereFieldValue<_.output<ZodObject<S>>[K]>
+} & {
+  own?: boolean
+}
+type WhereOf<S extends ZodRawShape> = WhereGroupOf<S> & {
+  or?: WhereGroupOf<S>[]
+}
+type WithUrls<D> = D & { [K in keyof D as UrlKey<K, D[K]>]: UrlVal<D[K]> }
+export type {
+  Ab,
+  ActionCtxLike,
+  AuthorInfo,
+  BaseBuilders,
+  CacheBuilders,
+  CacheCrudResult,
+  CacheOptions,
+  CanEditOpts,
+  ChildConfig,
+  ChildCrudResult,
+  ComparisonOp,
+  CrudBuilders,
+  CrudOptions,
+  CrudReadApi,
+  CrudResult,
+  DbCtx,
+  DbLike,
+  DbReadLike,
+  DocBase,
+  EnrichedDoc,
+  ErrorCode,
+  FID,
+  FilterLike,
+  IndexLike,
+  Mb,
+  MutationCtxLike,
+  MutCtx,
+  OrgCrudResult,
+  OrgEnrichedDoc,
+  OrgRole,
+  PaginatedResult,
+  PaginationOptsShape,
+  Qb,
+  QueryCtxLike,
+  QueryLike,
+  ReadCtx,
+  Rec,
+  SearchLike,
+  SetupConfig,
+  StorageLike,
+  UserCtx,
+  WhereGroupOf,
+  WhereOf,
+  WithUrls
+}
+export { ERROR_MESSAGES }

package/src/server/unique.ts

@@ -0,0 +1,28 @@
+import type { RegisteredQuery } from 'convex/server'
+
+import { zid } from 'convex-helpers/server/zod4'
+import { string } from 'zod/v4'
+
+import type { FilterLike, Qb, QueryCtxLike } from './types'
+
+const makeUnique = ({
+  field,
+  pq,
+  table
+}: {
+  field: string
+  pq: Qb
+  table: string
+}): RegisteredQuery<'public', { exclude?: string; value: string }, boolean> =>
+  pq({
+    args: { exclude: zid(table).optional(), value: string() },
+    handler: (async (c: QueryCtxLike, { exclude, value }: { exclude?: string; value: string }) => {
+      const existing = await c.db
+        .query(table)
+        .filter((f: FilterLike) => f.eq(f.field(field), value))
+        .first()
+      return !(existing as null | Record<string, unknown>) || (existing as Record<string, unknown>)._id === exclude
+    }) as never
+  }) as never
+
+export { makeUnique }

package/src/zod.ts

@@ -0,0 +1,141 @@
+import type { core, output, ZodObject, ZodRawShape, ZodType } from 'zod/v4'
+
+type CvMeta = 'file' | 'files'
+type DefType = core.$ZodTypeDef['type']
+type ZodSchema = ZodType
+
+const WRAPPERS: ReadonlySet<DefType> = new Set<DefType>([
+    'catch',
+    'default',
+    'nullable',
+    'optional',
+    'prefault',
+    'readonly'
+  ]),
+  unwrapZod = (
+    schema: unknown
+  ): {
+    def: undefined | ZodSchema['def']
+    schema: undefined | ZodSchema
+    type: '' | DefType
+  } => {
+    let cur = schema as undefined | ZodSchema
+    while (cur && typeof cur === 'object' && 'type' in cur) {
+      if (!WRAPPERS.has(cur.type)) return { def: cur.def, schema: cur, type: cur.type }
+      cur = (cur.def as { innerType?: ZodSchema }).innerType
+    }
+    return { def: undefined, schema: undefined, type: '' }
+  },
+  isOptionalField = (schema: unknown): boolean => {
+    let cur = schema as undefined | ZodSchema
+    while (cur && typeof cur === 'object' && 'type' in cur) {
+      if (cur.type === 'optional') return true
+      if (!WRAPPERS.has(cur.type)) return false
+      cur = (cur.def as { innerType?: ZodSchema }).innerType
+    }
+    return false
+  },
+  elementOf = (s: undefined | ZodSchema): unknown => (s?.def as undefined | { element?: unknown })?.element,
+  cvMetaOf = (schema: undefined | ZodSchema): CvMeta | undefined => {
+    if (!schema || typeof schema.meta !== 'function') return
+    const m = schema.meta() as undefined | { cv?: unknown }
+    if (m && typeof m === 'object') {
+      const { cv } = m
+      if (cv === 'file' || cv === 'files') return cv
+    }
+  },
+  isArrayType = (t: '' | DefType) => t === 'array',
+  isBooleanType = (t: '' | DefType) => t === 'boolean',
+  isDateType = (t: '' | DefType) => t === 'date',
+  isNumberType = (t: '' | DefType) => t === 'number',
+  isStringType = (t: '' | DefType) => t === 'string' || t === 'enum',
+  cvFileKindOf = (schema: unknown): CvMeta | undefined => {
+    const { schema: s, type } = unwrapZod(schema),
+      cv = cvMetaOf(s)
+    if (cv) return cv
+    if (isArrayType(type) && cvMetaOf(elementOf(s) as undefined | ZodSchema) === 'file') return 'files'
+  },
+  enumToOptions = <T extends string>(
+    schema: { options: readonly T[] },
+    transform?: (v: T) => string
+  ): {
+    label: string
+    value: T
+  }[] =>
+    schema.options.map(v => ({
+      label: transform?.(v) ?? v.charAt(0).toUpperCase() + v.slice(1),
+      value: v
+    })),
+  requiredPartial = <S extends ZodObject<ZodRawShape>>(
+    schema: S,
+    requiredKeys: (keyof S['shape'])[]
+  ): ZodObject<ZodRawShape> => {
+    const partial = schema.partial(),
+      required = Object.fromEntries(requiredKeys.map(k => [k, true])) as Record<string, true>
+    return partial.required(required) as ZodObject<ZodRawShape>
+  },
+  // eslint-disable-next-line max-statements
+  defaultValue = (schema: unknown): unknown => {
+    const { schema: base, type } = unwrapZod(schema),
+      fk = cvFileKindOf(schema)
+    if (fk === 'file') return null
+    if (fk === 'files') return []
+    if (isArrayType(type)) return []
+    if (isBooleanType(type)) return false
+    if (isNumberType(type)) return 0
+    if (isStringType(type)) {
+      if (base && 'options' in base) {
+        const opts = (base as { options: readonly string[] }).options
+        if (opts.length) return opts[0]
+      }
+      return ''
+    }
+    if (isDateType(type)) return null
+    const inner = (base?.def as undefined | { innerType?: unknown })?.innerType
+    if (inner) return defaultValue(inner)
+  },
+  defaultValues = <S extends ZodObject<ZodRawShape>>(schema: S): output<S> => {
+    const result: Record<string, unknown> = {}
+    // biome-ignore lint/nursery/noForIn: iterating shape keys with hasOwn guard
+    for (const k in schema.shape) if (Object.hasOwn(schema.shape, k)) result[k] = defaultValue(schema.shape[k])
+    return result as output<S>
+  },
+  pickValues = <S extends ZodObject<ZodRawShape>>(schema: S, doc: object): output<S> => {
+    const d = doc as Record<string, unknown>,
+      result: Record<string, unknown> = {}
+    // biome-ignore lint/nursery/noForIn: iterating shape keys with hasOwn guard
+    for (const k in schema.shape) if (Object.hasOwn(schema.shape, k)) result[k] = d[k] ?? defaultValue(schema.shape[k])
+    return result as output<S>
+  },
+  coerceOptionals = <S extends ZodObject<ZodRawShape>>(schema: S, data: output<S>): output<S> => {
+    const result: Record<string, unknown> = { ...data }
+    for (const k of Object.keys(result))
+      if (isOptionalField(schema.shape[k]) && isStringType(unwrapZod(schema.shape[k]).type)) {
+        const v = result[k]
+        if (typeof v === 'string') {
+          const trimmed = v.trim()
+          result[k] = trimmed.length > 0 ? trimmed : undefined
+        }
+      }
+    return result as output<S>
+  }
+
+export type { CvMeta, DefType, ZodSchema }
+export {
+  coerceOptionals,
+  cvFileKindOf,
+  cvMetaOf,
+  defaultValue,
+  defaultValues,
+  elementOf,
+  enumToOptions,
+  isArrayType,
+  isBooleanType,
+  isDateType,
+  isNumberType,
+  isOptionalField,
+  isStringType,
+  pickValues,
+  requiredPartial,
+  unwrapZod
+}