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 = 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(schema: z.ZodType, 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 { rows: Row[] next: Cursor | null }