@lota-sdk/core 0.4.8 → 0.4.9

package/src/db/record-id.ts

@@ -1,7 +1,8 @@
+import { Effect } from 'effect'
 import type { RecordIdValue } from 'surrealdb'
 import { RecordId, StringRecordId } from 'surrealdb'
 
-import { BadRequestError } from '../utils/errors'
+import { BadRequestError } from '../effect/errors'
 
 export interface RecordIdShape {
   tb: string
@@ -21,13 +22,6 @@ interface NamedConstructor {
   name?: unknown
 }
 
-class InvalidRecordIdError extends BadRequestError {
-  constructor(message: string) {
-    super(message)
-    this.name = 'InvalidRecordIdError'
-  }
-}
-
 export function isSurrealRecordIdValue(value: unknown): boolean {
   if (!value || typeof value !== 'object') {
     return false
@@ -42,6 +36,23 @@ export function isSurrealRecordIdValue(value: unknown): boolean {
   return typeof constructorName === 'string' && SURREAL_RECORD_ID_CLASS_NAMES.has(constructorName)
 }
 
+export function isRecordIdInput(value: unknown): value is RecordIdInput {
+  if (typeof value === 'string' || value instanceof RecordId || value instanceof StringRecordId) {
+    return true
+  }
+
+  if (isSurrealRecordIdValue(value)) {
+    return true
+  }
+
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+
+  const record = value as { tb?: unknown; id?: unknown }
+  return typeof record.tb === 'string' && record.id !== undefined
+}
+
 export function ensureRecordId(value: RecordIdInput, fallbackTable?: string): RecordId {
   if (value instanceof RecordId) {
     return value
@@ -58,7 +69,7 @@ export function ensureRecordId(value: RecordIdInput, fallbackTable?: string): Re
       return new RecordId(tableIdMatch[1], tableIdMatch[2])
     }
     if (!fallbackTable) {
-      throw new InvalidRecordIdError('Missing table for record id')
+      throw new BadRequestError({ message: 'Missing table for record id' })
     }
     return new RecordId(fallbackTable, value)
   }
@@ -70,9 +81,20 @@ export function ensureRecordId(value: RecordIdInput, fallbackTable?: string): Re
     }
   }
 
-  throw new InvalidRecordIdError('Invalid record id value')
+  throw new BadRequestError({ message: 'Invalid record id value' })
 }
 
 export function recordIdToString(value: RecordIdInput, fallbackTable?: string): string {
   return ensureRecordId(value, fallbackTable).toString()
 }
+
+export function ensureRecordIdEffect(
+  value: RecordIdInput,
+  fallbackTable?: string,
+): Effect.Effect<RecordId, BadRequestError> {
+  return Effect.try({
+    try: () => ensureRecordId(value, fallbackTable),
+    catch: (error) =>
+      new BadRequestError({ message: error instanceof Error ? error.message : 'Invalid record id value' }),
+  })
+}

package/src/db/schema-fingerprint.ts

@@ -1,20 +1,38 @@
+import { Schema, Effect } from 'effect'
+
+import { createSha256Hasher } from '../utils/crypto'
+
 function toSchemaFilePath(value: string | URL): string {
   return value instanceof URL ? value.pathname : value
 }
 
-export async function computeSchemaFingerprint(schemaFiles: readonly (string | URL)[]): Promise<string> {
-  const hash = new Bun.CryptoHasher('sha256')
+class SchemaFingerprintError extends Schema.TaggedErrorClass<SchemaFingerprintError>()('SchemaFingerprintError', {
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+export function computeSchemaFingerprint(schemaFiles: readonly (string | URL)[]): Promise<string> {
+  return Effect.runPromise(
+    Effect.gen(function* () {
+      const hash = createSha256Hasher()
+
+      for (const schemaFile of schemaFiles) {
+        const sortKey = toSchemaFilePath(schemaFile)
+        const file = schemaFile instanceof URL ? Bun.file(schemaFile.pathname) : Bun.file(schemaFile)
+
+        hash.update(sortKey)
+        hash.update('\0')
 
-  // Sequential reads required: hash must be computed in deterministic file order
-  for (const schemaFile of schemaFiles) {
-    const sortKey = toSchemaFilePath(schemaFile)
-    const file = schemaFile instanceof URL ? Bun.file(schemaFile.pathname) : Bun.file(schemaFile)
+        const contents = yield* Effect.tryPromise({
+          try: () => file.text(),
+          catch: (cause) => new SchemaFingerprintError({ message: `Failed to read schema file ${sortKey}.`, cause }),
+        })
 
-    hash.update(sortKey)
-    hash.update('\0')
-    hash.update((await file.text()).trim())
-    hash.update('\0')
-  }
+        hash.update(contents.trim())
+        hash.update('\0')
+      }
 
-  return hash.digest('hex')
+      return hash.digest('hex')
+    }),
+  )
 }

package/src/db/service-normalization.ts

@@ -0,0 +1,255 @@
+/**
+ * Normalization helpers for SurrealDB service inputs.
+ *
+ * Functions in this module throw `SurrealDBError` on invalid inputs.
+ * Callers in `service.ts` invoke these inside `Effect.tryPromise` `try` blocks
+ * or `Effect.gen` generators, so thrown errors are caught by the surrounding
+ * `catch` handler and surfaced as typed `SurrealDBError` failures.
+ * Do not call these outside an Effect error boundary.
+ */
+import { Schema } from 'effect'
+import { BoundQuery, RecordId, StringRecordId, Table, and, eq } from 'surrealdb'
+import type { ExprLike, Mutation } from 'surrealdb'
+import type { z } from 'zod'
+
+import { isRecord } from '../utils/string'
+import type { RecordIdInput } from './record-id'
+import { ensureRecordId, isRecordIdInput, isSurrealRecordIdValue } from './record-id'
+import type { DatabaseTable } from './tables'
+
+export class SurrealDBError extends Schema.TaggedErrorClass<SurrealDBError>()('SurrealDBError', {
+  message: Schema.String,
+  query: Schema.optional(Schema.String),
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+export type RecordMutation = Extract<Mutation, 'content' | 'replace' | 'merge'>
+
+type TransactionQueryDescriptor = { query: string; bindings?: Record<string, unknown> }
+
+type ParseSchema = <TSchema extends z.ZodTypeAny>(schema: TSchema, value: unknown) => z.infer<TSchema>
+
+function isExplicitRecordIdValue(value: unknown): value is RecordIdInput {
+  if (value instanceof RecordId || value instanceof StringRecordId) {
+    return true
+  }
+
+  if (isSurrealRecordIdValue(value)) {
+    return true
+  }
+
+  if (!isRecord(value)) {
+    return false
+  }
+
+  return typeof value.tb === 'string' && value.id !== undefined && Object.keys(value).length === 2
+}
+
+export function configureMutation<
+  TBuilder extends {
+    content: (data: Record<string, unknown>) => TBuilder
+    replace: (data: Record<string, unknown>) => TBuilder
+    merge: (data: Record<string, unknown>) => TBuilder
+  },
+>(builder: TBuilder, mutation: RecordMutation, data: Record<string, unknown>): TBuilder {
+  if (mutation === 'content') {
+    return builder.content(data)
+  }
+  if (mutation === 'replace') {
+    return builder.replace(data)
+  }
+  return builder.merge(data)
+}
+
+function isTransactionQueryDescriptor(value: unknown): value is TransactionQueryDescriptor {
+  return isRecord(value) && typeof value.query === 'string'
+}
+
+export function normalizeTransactionRecordId(value: unknown, context: string): RecordId {
+  if (!isRecordIdInput(value)) {
+    throw new SurrealDBError({ message: `Invalid record id for ${context}` })
+  }
+
+  return ensureRecordId(value)
+}
+
+export function normalizeRecordIdForTable(id: unknown, table: DatabaseTable): ReturnType<typeof ensureRecordId> {
+  try {
+    if (!isRecordIdInput(id)) {
+      throw new SurrealDBError({ message: `Invalid record id for table "${table}"` })
+    }
+
+    const recordId = ensureRecordId(id, table)
+    const resolvedTable = String(recordId.table)
+    if (resolvedTable !== table) {
+      throw new SurrealDBError({ message: `Record id table mismatch: expected "${table}" but got "${resolvedTable}"` })
+    }
+    return recordId
+  } catch (error) {
+    if (error instanceof SurrealDBError) {
+      throw error
+    }
+    if (error instanceof Error) {
+      throw new SurrealDBError({ message: `Invalid record id for table "${table}": ${error.message}`, cause: error })
+    }
+    throw new SurrealDBError({ message: `Invalid record id for table "${table}"` })
+  }
+}
+
+export function normalizeSurrealValue(value: unknown): unknown {
+  if (
+    value === null ||
+    value === undefined ||
+    value instanceof Date ||
+    value instanceof RecordId ||
+    value instanceof StringRecordId ||
+    value instanceof Table
+  ) {
+    return value
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeSurrealValue(entry))
+  }
+
+  if (isExplicitRecordIdValue(value)) {
+    return ensureRecordId(value)
+  }
+
+  if (!isRecord(value)) {
+    return value
+  }
+
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, normalizeSurrealValue(entry)]))
+}
+
+export function normalizeQueryRows(
+  statement: unknown,
+  schema: z.ZodTypeAny | undefined,
+  parseSchema: ParseSchema,
+): unknown[] {
+  if (Array.isArray(statement)) {
+    return schema ? statement.map((row) => parseSchema(schema, row)) : statement
+  }
+  if (statement === null || statement === undefined) {
+    return []
+  }
+  return schema ? [parseSchema(schema, statement)] : [statement]
+}
+
+export function assertValidIdentifier(name: string, context: string): void {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(name)) {
+    throw new SurrealDBError({ message: `Invalid ${context}: "${name}"` })
+  }
+}
+
+export function buildFilterExpression(filter: Record<string, unknown>): ExprLike | undefined {
+  const entries = Object.entries(filter)
+  if (entries.length === 0) {
+    return undefined
+  }
+
+  const expressions = entries.map(([key, value]) => eq(key, normalizeSurrealValue(value)))
+  if (expressions.length === 1) {
+    return expressions[0]
+  }
+
+  return and(...expressions)
+}
+
+export function buildBoundFilterClauses(filter: Record<string, unknown>): {
+  clause: string
+  bindings: Record<string, unknown>
+} {
+  const entries = Object.entries(filter)
+  if (entries.length === 0) {
+    throw new SurrealDBError({ message: 'Expected a non-empty filter' })
+  }
+
+  const bindings: Record<string, unknown> = {}
+  const clauses = entries.map(([field, value], index) => {
+    assertValidIdentifier(field, 'filter field')
+
+    const bindingKey = `filter_${index}`
+    bindings[bindingKey] = normalizeSurrealValue(value)
+    return `${field} = $${bindingKey}`
+  })
+
+  return { clause: clauses.join(' AND '), bindings }
+}
+
+export function normalizeBoundQuery<T extends unknown[] = unknown[]>(query: BoundQuery<T>): BoundQuery<T> {
+  return new BoundQuery<T>(query.query, normalizeBindings(query.bindings))
+}
+
+export function normalizeTransactionQuery(query: unknown): BoundQuery {
+  if (query instanceof BoundQuery) {
+    return new BoundQuery(query.query, normalizeBindings(query.bindings))
+  }
+
+  if (isTransactionQueryDescriptor(query)) {
+    return new BoundQuery(query.query, normalizeBindings(query.bindings))
+  }
+
+  throw new SurrealDBError({ message: 'Invalid transaction query' })
+}
+
+function normalizeBindings(bindings?: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (!bindings) {
+    return undefined
+  }
+
+  const normalized = normalizeSurrealValue(bindings)
+  if (!isRecord(normalized)) {
+    throw new SurrealDBError({ message: 'Invalid bindings value' })
+  }
+
+  return normalized
+}
+
+export function normalizeMutationData(data: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(data)
+      .map(([key, value]) => [key, value === undefined ? undefined : normalizeSurrealValue(value)] as const)
+      .filter((entry): entry is readonly [string, unknown] => entry[1] !== undefined),
+  )
+}
+
+export function normalizeTableValue(value: unknown): Table<string> {
+  if (value instanceof Table) {
+    return new Table<string>(value.name as string)
+  }
+
+  if (typeof value === 'string' && value.length > 0) {
+    return new Table(value)
+  }
+
+  throw new SurrealDBError({ message: 'Invalid table value' })
+}
+
+export function normalizeCreateTarget(value: unknown): Table<string> | RecordId {
+  if (
+    isExplicitRecordIdValue(value) ||
+    (typeof value === 'string' && isRecordIdInput(value) && /^[A-Za-z_][A-Za-z0-9_]*:/.test(value))
+  ) {
+    return ensureRecordId(value)
+  }
+
+  return normalizeTableValue(value)
+}
+
+export function describeInvalidValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value
+  }
+
+  try {
+    const serialized = JSON.stringify(value)
+    if (typeof serialized === 'string') {
+      return serialized
+    }
+    return Object.prototype.toString.call(value)
+  } catch {
+    return Object.prototype.toString.call(value)
+  }
+}