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.
95 lines
2.9 KiB
TypeScript
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
|
|
}
|