@lota-sdk/core 0.4.8 → 0.4.10

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,288 @@
+/**
+ * Normalization helpers for SurrealDB service inputs.
+ *
+ * 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 { Effect, 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 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
+  }
+
+  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): Effect.Effect<RecordId, SurrealDBError> {
+  if (!isRecordIdInput(value)) {
+    return Effect.fail(new SurrealDBError({ message: `Invalid record id for ${context}` }))
+  }
+
+  return Effect.try({
+    try: () => ensureRecordId(value),
+    catch: (error) => toSurrealDBError(error, `Invalid record id for ${context}`),
+  })
+}
+
+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 {
+  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): Effect.Effect<void, SurrealDBError> {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(name)) {
+    return Effect.fail(new SurrealDBError({ message: `Invalid ${context}: "${name}"` }))
+  }
+  return Effect.void
+}
+
+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>,
+): Effect.Effect<{ clause: string; bindings: Record<string, unknown> }, SurrealDBError> {
+  const entries = Object.entries(filter)
+  if (entries.length === 0) {
+    return Effect.fail(new SurrealDBError({ message: 'Expected a non-empty filter' }))
+  }
+
+  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}`)
+    }
+
+    return { clause: clauses.join(' AND '), 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): Effect.Effect<BoundQuery, SurrealDBError> {
+  if (query instanceof BoundQuery) {
+    return Effect.map(normalizeBindings(query.bindings), (bindings) => new BoundQuery(query.query, bindings))
+  }
+
+  if (isTransactionQueryDescriptor(query)) {
+    return Effect.map(normalizeBindings(query.bindings), (bindings) => new BoundQuery(query.query, bindings))
+  }
+
+  return Effect.fail(new SurrealDBError({ message: 'Invalid transaction query' }))
+}
+
+function normalizeBindings(
+  bindings?: Record<string, unknown>,
+): Effect.Effect<Record<string, unknown> | undefined, SurrealDBError> {
+  if (!bindings) {
+    return Effect.void as Effect.Effect<undefined, SurrealDBError>
+  }
+
+  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> {
+  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): Effect.Effect<Table<string>, SurrealDBError> {
+  if (value instanceof Table) {
+    return Effect.succeed(new Table<string>(value.name as string))
+  }
+
+  if (typeof value === 'string' && value.length > 0) {
+    return Effect.succeed(new Table(value))
+  }
+
+  return Effect.fail(new SurrealDBError({ message: 'Invalid table value' }))
+}
+
+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 Effect.try({
+      try: () => ensureRecordId(value),
+      catch: (error) => toSurrealDBError(error, 'Invalid record id'),
+    })
+  }
+
+  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)
+  }
+}