Observations

observations records measurements of a record: a patient's heart rate, a machine's temperature, a client's weight. A definition says what is measured, in which unit and with which code, and which values are valid, normal and critical. Each observation gets a flag from those ranges, a critical value alerts the record's leads, and a correction keeps the original as amended.

better-supabase add observations

import { createObservations } from "better-supabase/blocks/observations";

The module requires memberships, permissions and subjects: an observation belongs to any record type in config.subjects, and the caller needs access to that record. With forms a submitted form records observations, with notifications a critical value notifies the record's leads, with outbox it records the events, and with audit every change is audited.

TablesCopy Anchor Link

Members read their organizations' definitions and the system ones. Reading an observation also needs access to its record, and the rest needs a permission:

Admins have all three; members get read and record.

DefinitionsCopy Anchor Link

Set options.defaults to vitals to install nine system definitions every organization reads, each with its LOINC code and UCUM unit:

blocks: {
  observations: { options: { defaults: "vitals" } },
},

An organization adds its own, such as an early warning score:

await db.observations
  .saveDefinition(organizationId, "mews", {
    title: "Modified early warning score",
    valueType: "integer",
    unit: "{score}",
    validLow: 0,
    validHigh: 14,
    referenceHigh: 2,
    criticalHigh: 5,
  })
  .orThrow();

saveDefinition creates the definition or updates the one with the same key, and restores it if it was archived. A key a system definition uses overrides it for that organization. archiveDefinition stops a definition from taking new observations; its observations stay. definitions lists the organization's and the system ones by title, with { includeArchived: true } for the archived ones too.

A components definition has one to twenty components, each with a key, and optionally a title, code, unit, decimals, its own ranges and optional: true. A value needs every component that isn't optional.

Ranges and flagsCopy Anchor Link

A value outside the valid range is refused with OBSERVATION_VALUE_INVALID. Inside it, the flag is critical_low or critical_high at or past a critical bound, low or high outside the reference range, and normal otherwise. A definition without ranges leaves the flag out. A components value takes the furthest flag of its parts.

RecordingCopy Anchor Link

const reading = await db.observations
  .record(organizationId, {
    subjectType: "patient",
    subjectId: patientId,
    definitionKey: "heart_rate",
    value: 135,
    method: "palpation",
  })
  .orThrow();
// reading.flag is "critical_high"

observedAt defaults to now and may not be in the future. recordMany records up to 500 observations, all or none. A critical value records observation.critical_recorded and, with notifications installed, notifies each member of the record's team with the role lead, except the caller.

ingest takes readings from a device or an import with the service role. Each item carries an externalId; an item ingested before is skipped, so a retried batch records nothing twice:

const result = await observations
  .ingest(organizationId, [
    {
      subjectType: "patient",
      subjectId: patientId,
      definitionKey: "oxygen_saturation",
      value: 94,
      observedAt: Temporal.Instant.from("2026-10-30T08:00:00Z"),
      externalId: "oximeter-17:1730275200",
      device: "oximeter-17",
    },
  ])
  .orThrow();
// { inserted: 1, skipped: 0, ids: ["…"] }

CorrectionsCopy Anchor Link

const corrected = await db.observations
  .amend(reading.id, { value: 115 }, "Counted over 15 seconds")
  .orThrow();
// corrected.replacesId is reading.id, reading's status is now "amended"

amend records the corrected observation and marks the original amended; what the changes leave out stays. markError(observationId, reason) marks one entered_in_error, and marking twice keeps the first reason. Neither deletes anything.

ReadingCopy Anchor Link

const latest = await db.observations.latest("patient", patientId).orThrow();
// { heart_rate: { value: 115, flag: "high", … }, blood_pressure: { … } }

const points = await db.observations
  .series("patient", patientId, "heart_rate", {
    since: Temporal.Now.instant().subtract({ hours: 24 }),
  })
  .orThrow();
// [{ id, observedAt, value, flag }], oldest first

const daily = await db.observations
  .buckets("patient", patientId, "blood_pressure", "day")
  .orThrow();
// [{ bucket, count, min, max, avg, components: { systolic: { min, max, avg } } }]

list returns a record's observations, the latest first, filtered by definitionKey; it leaves out amended and entered-in-error ones unless you pass includeAll: true. limit defaults to 100, at most 1,000. series, buckets and latest only read final values. buckets groups by UTC hour, day, week or month, with until excluded from the range.

The observation chart recipe renders the latest values with their flags and a sparkline of each series.

From a formCopy Anchor Link

With forms installed, a form field maps to a definition through meta.observation, and to one component through meta.component:

fields: [
  { key: "pulse", label: "Pulse", type: "number", meta: { observation: "heart_rate" } },
  { key: "sys", label: "Systolic", type: "number", meta: { observation: "blood_pressure", component: "systolic" } },
  { key: "dia", label: "Diastolic", type: "number", meta: { observation: "blood_pressure", component: "diastolic" } },
],

A submission about a record (submit_form with a subject) records its observations with source: "form" and the submissionId, in the same transaction. fromSubmission(submissionId) records them for a submission made before the mapping, and a submission is recorded only once.

FHIRCopy Anchor Link

The columns follow the FHIR R4 Observation resource, so an export maps one to one: the definition's codeSystem and code are Observation.code, the unit is a UCUM code, components are Observation.component, the flag is the interpretation (N, L, H, LL, HH), and final, amended and entered_in_error are FHIR statuses.

OptionsCopy Anchor Link

Pass a Standard Schema as fields to type the extra columns, parse them on reads and validate them on record:

const observations = createObservations({
  transport,
  fields: z.object({ ward: z.string().optional() }),
});

Adopting tablesCopy Anchor Link

An app with its own tables keeps them: the module runs over them and maps their columns. The definition's timestamps are optional; map them to null and the module leaves them out.

blocks: {
  observations: {
    tables: {
      definitions: "public.measurement_types",
      observations: "public.measurements",
    },
    columns: {
      definitions: { title: "name", createdAt: null, updatedAt: null },
    },
  },
},

EventsCopy Anchor Link

HooksCopy Anchor Link

before_observation_definition_save, after_observation_definition_save, before_observation_record, after_observation_record, before_observation_amend, after_observation_amend, before_observation_mark_error and after_observation_mark_error run in the same transaction as the change. See extending blocks.

ErrorsCopy Anchor Link

Without the clientCopy Anchor Link

db.observations is this client. Code that does not go through bsb.db() builds it with a transport:

import { createObservations } from "better-supabase/blocks/observations";

const observations = createObservations({ transport });
const latest = await observations.latest("patient", patientId).orThrow();