Files
faunosteo/packages/supabase/src/records.ts
T
bchanot e22357630f feat(supabase): animals and relations access layer
animals.ts: POST search with species filter and a probe row, read by id with
explicit columns, create with the optional first client in one call, update,
archive. relations.ts: an animal's relations in one select (voided left out),
create, end, dates, void. Kinds duplicate_relation and already_ended added.
2026-10-26 17:11:23 +01:00

95 lines
2.9 KiB
TypeScript

import type { z } from 'zod'
/**
* Closed failure kinds of the V1-1 record reads and RPCs (clients, animals,
* relations): contract docs/development/V1-1_OWNERS_ANIMALS.md §9.4. The
* server answers closed codes, never values; this module folds them, the
* session and the network into one kind the UI phrases. A foreign id and an
* unknown one are the same `not_found`, as the server makes them.
*/
export const RECORD_FAILURE_KINDS = [
'not_found',
'archived',
'conflict',
'request_conflict',
'limit_reached',
'rate_limited',
'invalid_input',
'duplicate_relation',
'already_ended',
'session_expired',
'network',
'unavailable',
] as const
export type RecordFailureKind = (typeof RECORD_FAILURE_KINDS)[number]
export class RecordFailure extends Error {
readonly kind: RecordFailureKind
constructor(kind: RecordFailureKind, cause?: unknown) {
super(`record: ${kind}`, { cause })
this.name = 'RecordFailure'
this.kind = kind
}
}
/** Messages the record RPCs raise with SQLSTATE P0001 (contract §9.4). */
const RPC_MESSAGE_KINDS: ReadonlySet<string> = new Set([
'archived',
'conflict',
'request_conflict',
'limit_reached',
'rate_limited',
'invalid_input',
'duplicate_relation',
'already_ended',
])
interface PostgrestLikeError {
code?: string | null
message?: string
}
/**
* Folds a PostgREST answer into a closed kind. `status` is the HTTP status
* postgrest-js returns beside the error: 0 when the request never got an
* answer, 401 when the JWT is missing or expired (PGRST30x).
*/
export function classifyRecordError(
error: unknown,
status?: number,
): RecordFailureKind {
if (error instanceof RecordFailure) return error.kind
if (error instanceof TypeError) return 'network'
const e = (error ?? {}) as PostgrestLikeError
if (e.code === '42501' && e.message === 'not_found') return 'not_found'
if (e.code === 'P0001' && e.message && RPC_MESSAGE_KINDS.has(e.message)) {
return e.message as RecordFailureKind
}
if (status === 401 || e.code?.startsWith('PGRST30')) return 'session_expired'
if (status === 0) return 'network'
return 'unavailable'
}
/** Throws the closed failure of a PostgREST answer. */
export function failRecord(error: unknown, status?: number): never {
throw new RecordFailure(classifyRecordError(error, status), error)
}
/** The RPC answer checked against its contract; a different shape is `unavailable`. */
export function parseRecordAnswer<T>(schema: z.ZodType<T>, data: unknown): T {
const result = schema.safeParse(data)
if (!result.success) throw new RecordFailure('unavailable', result.error)
return result.data
}
/** Ids are uuids: anything else is answered as unknown without a request. */
export const UUID_PATTERN =
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
/** One page of a keyset list; `next` is null on the last page. */
export interface RecordPage<Row, Cursor> {
rows: Row[]
next: Cursor | null
}