@lota-sdk/core 0.4.9 → 0.4.11

package/src/db/service-normalization.ts

@@ -1,13 +1,11 @@
 /**
  * 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.
+ * Helpers that can fail return `Effect<T, SurrealDBError>` so callers can
+ * `yield*` them inside `Effect.gen` and use `catchTag('SurrealDBError')`
+ * without losing the typed failure channel.
  */
-import { Schema } from 'effect'
+import { Effect, Schema } from 'effect'
 import { BoundQuery, RecordId, StringRecordId, Table, and, eq } from 'surrealdb'
 import type { ExprLike, Mutation } from 'surrealdb'
 import type { z } from 'zod'
@@ -29,6 +27,20 @@ type TransactionQueryDescriptor = { query: string; bindings?: Record<string, unk
 
 type ParseSchema = <TSchema extends z.ZodTypeAny>(schema: TSchema, value: unknown) => z.infer<TSchema>
 
+function isSurrealDBError(error: unknown): error is SurrealDBError {
+  return isRecord(error) && error._tag === 'SurrealDBError'
+}
+
+function toSurrealDBError(error: unknown, fallbackMessage: string): SurrealDBError {
+  if (isSurrealDBError(error)) {
+    return error
+  }
+  if (error instanceof Error) {
+    return new SurrealDBError({ message: `${fallbackMessage}: ${error.message}`, cause: error })
+  }
+  return new SurrealDBError({ message: fallbackMessage })
+}
+
 function isExplicitRecordIdValue(value: unknown): value is RecordIdInput {
   if (value instanceof RecordId || value instanceof StringRecordId) {
     return true
@@ -65,35 +77,38 @@ function isTransactionQueryDescriptor(value: unknown): value is TransactionQuery
   return isRecord(value) && typeof value.query === 'string'
 }
 
-export function normalizeTransactionRecordId(value: unknown, context: string): RecordId {
+export function normalizeTransactionRecordId(value: unknown, context: string): Effect.Effect<RecordId, SurrealDBError> {
   if (!isRecordIdInput(value)) {
-    throw new SurrealDBError({ message: `Invalid record id for ${context}` })
+    return Effect.fail(new SurrealDBError({ message: `Invalid record id for ${context}` }))
   }
 
-  return ensureRecordId(value)
+  return Effect.try({
+    try: () => ensureRecordId(value),
+    catch: (error) => toSurrealDBError(error, `Invalid record id for ${context}`),
+  })
 }
 
-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 normalizeRecordIdForTable(
+  id: unknown,
+  table: DatabaseTable,
+): Effect.Effect<ReturnType<typeof ensureRecordId>, SurrealDBError> {
+  if (!isRecordIdInput(id)) {
+    return Effect.fail(new SurrealDBError({ message: `Invalid record id for table "${table}"` }))
   }
+
+  return Effect.try({
+    try: () => {
+      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) => toSurrealDBError(error, `Invalid record id for table "${table}"`),
+  })
 }
 
 export function normalizeSurrealValue(value: unknown): unknown {
@@ -137,10 +152,11 @@ export function normalizeQueryRows(
   return schema ? [parseSchema(schema, statement)] : [statement]
 }
 
-export function assertValidIdentifier(name: string, context: string): void {
+export function assertValidIdentifier(name: string, context: string): Effect.Effect<void, SurrealDBError> {
   if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(name)) {
-    throw new SurrealDBError({ message: `Invalid ${context}: "${name}"` })
+    return Effect.fail(new SurrealDBError({ message: `Invalid ${context}: "${name}"` }))
   }
+  return Effect.void
 }
 
 export function buildFilterExpression(filter: Record<string, unknown>): ExprLike | undefined {
@@ -157,54 +173,68 @@ export function buildFilterExpression(filter: Record<string, unknown>): ExprLike
   return and(...expressions)
 }
 
-export function buildBoundFilterClauses(filter: Record<string, unknown>): {
-  clause: string
-  bindings: Record<string, unknown>
-} {
+export function buildBoundFilterClauses(
+  filter: Record<string, unknown>,
+): Effect.Effect<{ clause: string; bindings: Record<string, unknown> }, SurrealDBError> {
   const entries = Object.entries(filter)
   if (entries.length === 0) {
-    throw new SurrealDBError({ message: 'Expected a non-empty filter' })
+    return Effect.fail(new SurrealDBError({ message: 'Expected a non-empty filter' }))
   }
 
-  const bindings: Record<string, unknown> = {}
-  const clauses = entries.map(([field, value], index) => {
-    assertValidIdentifier(field, 'filter field')
+  return Effect.gen(function* () {
+    const bindings: Record<string, unknown> = {}
+    const clauses: string[] = []
+    for (let index = 0; index < entries.length; index++) {
+      const [field, value] = entries[index]
+      yield* assertValidIdentifier(field, 'filter field')
+
+      const bindingKey = `filter_${index}`
+      bindings[bindingKey] = yield* Effect.try({
+        try: () => normalizeSurrealValue(value),
+        catch: (error) => toSurrealDBError(error, `Invalid filter value for field "${field}"`),
+      })
+      clauses.push(`${field} = $${bindingKey}`)
+    }
 
-    const bindingKey = `filter_${index}`
-    bindings[bindingKey] = normalizeSurrealValue(value)
-    return `${field} = $${bindingKey}`
+    return { clause: clauses.join(' AND '), bindings }
   })
-
-  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 normalizeBoundQuery<T extends unknown[] = unknown[]>(
+  query: BoundQuery<T>,
+): Effect.Effect<BoundQuery<T>, SurrealDBError> {
+  return Effect.map(normalizeBindings(query.bindings), (bindings) => new BoundQuery<T>(query.query, bindings))
 }
 
-export function normalizeTransactionQuery(query: unknown): BoundQuery {
+export function normalizeTransactionQuery(query: unknown): Effect.Effect<BoundQuery, SurrealDBError> {
   if (query instanceof BoundQuery) {
-    return new BoundQuery(query.query, normalizeBindings(query.bindings))
+    return Effect.map(normalizeBindings(query.bindings), (bindings) => new BoundQuery(query.query, bindings))
   }
 
   if (isTransactionQueryDescriptor(query)) {
-    return new BoundQuery(query.query, normalizeBindings(query.bindings))
+    return Effect.map(normalizeBindings(query.bindings), (bindings) => new BoundQuery(query.query, bindings))
   }
 
-  throw new SurrealDBError({ message: 'Invalid transaction query' })
+  return Effect.fail(new SurrealDBError({ message: 'Invalid transaction query' }))
 }
 
-function normalizeBindings(bindings?: Record<string, unknown>): Record<string, unknown> | undefined {
+function normalizeBindings(
+  bindings?: Record<string, unknown>,
+): Effect.Effect<Record<string, unknown> | undefined, SurrealDBError> {
   if (!bindings) {
-    return undefined
-  }
-
-  const normalized = normalizeSurrealValue(bindings)
-  if (!isRecord(normalized)) {
-    throw new SurrealDBError({ message: 'Invalid bindings value' })
+    return Effect.void as Effect.Effect<undefined, SurrealDBError>
   }
 
-  return normalized
+  return Effect.try({
+    try: () => {
+      const normalized = normalizeSurrealValue(bindings)
+      if (!isRecord(normalized)) {
+        throw new SurrealDBError({ message: 'Invalid bindings value' })
+      }
+      return normalized
+    },
+    catch: (error) => toSurrealDBError(error, 'Invalid bindings value'),
+  })
 }
 
 export function normalizeMutationData(data: Record<string, unknown>): Record<string, unknown> {
@@ -215,24 +245,27 @@ export function normalizeMutationData(data: Record<string, unknown>): Record<str
   )
 }
 
-export function normalizeTableValue(value: unknown): Table<string> {
+export function normalizeTableValue(value: unknown): Effect.Effect<Table<string>, SurrealDBError> {
   if (value instanceof Table) {
-    return new Table<string>(value.name as string)
+    return Effect.succeed(new Table<string>(value.name as string))
   }
 
   if (typeof value === 'string' && value.length > 0) {
-    return new Table(value)
+    return Effect.succeed(new Table(value))
   }
 
-  throw new SurrealDBError({ message: 'Invalid table value' })
+  return Effect.fail(new SurrealDBError({ message: 'Invalid table value' }))
 }
 
-export function normalizeCreateTarget(value: unknown): Table<string> | RecordId {
+export function normalizeCreateTarget(value: unknown): Effect.Effect<Table<string> | RecordId, SurrealDBError> {
   if (
     isExplicitRecordIdValue(value) ||
     (typeof value === 'string' && isRecordIdInput(value) && /^[A-Za-z_][A-Za-z0-9_]*:/.test(value))
   ) {
-    return ensureRecordId(value)
+    return Effect.try({
+      try: () => ensureRecordId(value),
+      catch: (error) => toSurrealDBError(error, 'Invalid record id'),
+    })
   }
 
   return normalizeTableValue(value)