Medications

medications keeps a medication chart for a client, patient or resident. An organization keeps its own list of medications, imported from a drug database or added by hand. A prescriber orders a medication for a record with a dose, a route and a schedule, or as needed with a maximum per day. The block plans the doses of scheduled orders, members record each one as given, refused or skipped, and doses nobody recorded in time become missed. A high-risk medication needs a second member to check every dose.

better-supabase add medications

import { createMedications } from "better-supabase/blocks/medications";

The module requires memberships, permissions and subjects: an order belongs to any record type registered in config.subjects. With notifications the members who manage medications hear about missed doses, with outbox the module records the events, and with audit every change is audited.

TablesCopy Anchor Link

A planned dose is unique per order and time, so planning twice adds nothing. Reading orders, doses and the chart needs medications.read and read access to the record, through the subjects block's can_subject.

Admins have all four; members get none, so grant them to the roles that prescribe and give medication.

Medication listCopy Anchor Link

const warfarin = await db.medications
  .saveMedication(organizationId, {
    name: "Warfarin",
    unit: "mg",
    codeSystem: "atc",
    code: "B01AA03",
    form: "tablet",
    strength: "1 mg",
    highRisk: true,
  })
  .orThrow();

const list = await db.medications
  .medications(organizationId, { search: "war" })
  .orThrow();

codeSystem is gtin, hpk (the Dutch G-Standaard), atc, rxnorm or custom, the default. A code is unique per code system in an organization. archiveMedication takes a medication off the list; its orders keep it. importMedication adds a catalog item, or updates the one with its code system and code.

Drug databasesCopy Anchor Link

The block bundles no drug data. Wrap your drug database's API in a MedicationCatalog and pass it as catalog:

import type { MedicationCatalog } from "better-supabase/blocks/medications";

const catalog: MedicationCatalog = {
  apiVersion: 1,
  search: async (query, { signal } = {}) => searchFormulary(query, signal),
  get: async (code, { signal } = {}) => formularyItem(code, signal),
};

const medications = createMedications({ transport, catalog });
const results = await medications.searchCatalog("paracetamol").orThrow();
await medications.importFromCatalog(organizationId, results[0].code).orThrow();

search returns items with a name, unit, codeSystem and code, and get returns one item or undefined. A catalog that throws returns an unexpected error with MEDICATION_CATALOG_FAILED. Test a catalog with testMedicationCatalog from better-supabase/testing, which checks the apiVersion, that searched items come back from get, that an unknown code is undefined, and that an aborted signal rejects:

import { testMedicationCatalog } from "better-supabase/testing";

await testMedicationCatalog(catalog, { query: "paracetamol" });

OrdersCopy Anchor Link

const order = await db.medications
  .prescribe(organizationId, { type: "client", id: clientId }, warfarin.id, {
    dose: 2,
    route: "oral",
    schedule: { times: ["08:00", "20:00"] },
    startsOn: Temporal.PlainDate.from("2026-11-02"),
    prescriber: "Dr. Visser",
  })
  .orThrow();

const asNeeded = await db.medications
  .prescribe(organizationId, subject, paracetamolId, {
    dose: 500,
    asNeeded: true,
    asNeededReason: "pain",
    maxPerDay: 2000,
  })
  .orThrow();

A scheduled order gives the times of day (HH:MM), or everyHours from a startTime, and optional ISO weekdays. An order without a schedule must be asNeeded. The dose unit defaults to the medication's unit and the start date to today, both in the block's time zone. A high-risk medication's orders need a double check; requiresDoubleCheck asks for one on any order.

updateOrder changes the dose, schedule, dates or other fields; a key it leaves out keeps its value and null clears it. pauseOrder and resumeOrder pause an order and resume it, and stopOrder(orderId, reason) stops it for good. Changing, pausing or stopping an order removes its planned doses after now, for planning to make again. ordersOf(subject) lists a record's orders with their medication, newest first.

The order fields follow FHIR R4 MedicationRequest: dose and doseUnit are its dosageInstruction.doseAndRate, schedule its timing, asNeeded and asNeededReason its asNeeded[x], and maxPerDay its maxDosePerPeriod. A dose follows MedicationAdministration.

Imported ordersCopy Anchor Link

const medications = createMedications({ transport, service });

const { created, skipped } = await medications
  .importOrders(organizationId, [
    {
      subject: { type: "client", id: clientId },
      externalId: "rx-2026-0412",
      medication: {
        name: "Metformin",
        unit: "mg",
        codeSystem: "atc",
        code: "A10BA02",
      },
      source: "pharmacy",
      dose: 500,
      schedule: { times: ["08:00"] },
    },
  ])
  .orThrow();

importOrders runs with the service role, so pass a service-role transport as service. Each order names a medicationId from the list or a catalog medication to add, and an externalId; an external id imported before is skipped, so a pharmacy feed can send its orders again.

DosesCopy Anchor Link

await db.medications
  .planAdministrations(
    organizationId,
    Temporal.Now.instant().add({ hours: 48 }),
  )
  .orThrow();

await db.medications
  .recordAdministration(doseId, { status: "given", checkedBy: colleagueId })
  .orThrow();

await db.medications
  .recordAsNeeded(asNeeded.id, { reason: "headache" })
  .orThrow();

planAdministrations plans the doses of the active scheduled orders up to a time at most 31 days ahead and returns how many it added. Run it daily from a job, with medications.manage or the service role.

recordAdministration records a planned or missed dose as given, refused or skipped; refused and skipped doses need a reason. The dose defaults to the order's. A high-risk dose needs checkedBy, another member with medications.administer. recordAsNeeded records a dose of an as-needed order and refuses one that would pass maxPerDay in 24 hours.

markMissed marks the planned doses more than missedAfterMinutes late as missed and returns how many. Run it from a job with the service role. With notifications installed, the members with medications.manage hear about each missed dose.

ChartCopy Anchor Link

const chart = await db.medications
  .chart({ type: "client", id: clientId })
  .orThrow();
// { since, until, orders: [{ ...order, medication }], administrations: [...] }

chart returns a record's orders and doses in a range, today in the block's time zone by default. The medication chart recipe renders it.

OptionsCopy Anchor Link

blocks: {
  medications: {
    options: { missedAfterMinutes: 30, timeZone: "Europe/Amsterdam" },
  },
},

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

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

Adopting tablesCopy Anchor Link

An app with its own medication list keeps it: the module runs over the table and maps its columns. The form, strength and timestamp columns are optional; map them to null and the module leaves them out.

blocks: {
  medications: {
    tables: { medications: "public.drugs" },
    columns: {
      medications: { tenant: "org_id", name: "label", form: null, strength: null },
    },
  },
},

EventsCopy Anchor Link

Resuming an order fires medication_order.updated, with status active.

HooksCopy Anchor Link

before_medication_order_prescribe, after_medication_order_prescribe, before_medication_order_stop, after_medication_order_stop, before_medication_administration_record and after_medication_administration_record run in the same transaction as the change. See extending blocks.

ErrorsCopy Anchor Link

Without the clientCopy Anchor Link

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

import { createMedications } from "better-supabase/blocks/medications";

const medications = createMedications({ transport });
const chart = await medications.chart(subject).orThrow();