@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.5

package/src/templates/instrumentRunAdapters.ts

@@ -0,0 +1,163 @@
+import type {
+  ProtocolStep,
+  ScheduleEvent,
+} from '../types'
+import { getTemplateData } from './templateEnvelopes'
+import { validateInstrumentRunData } from './templateValidators'
+import type {
+  InstrumentRunColumnsAdapterResult,
+  InstrumentRunDataFrameAdapterResult,
+  InstrumentRunRowsAdapterResult,
+  InstrumentRunScheduleEventsAdapterResult,
+  InstrumentRunStepsAdapterResult,
+  InstrumentRunTemplate,
+  InstrumentRunTemplateData,
+} from './types'
+import {
+  addMinutes,
+  dateFromMetadata,
+  instrumentRunScheduleColor,
+  instrumentRunScheduleStatus,
+  instrumentRunStepStatus,
+  instrumentRunStepType,
+} from './instrumentRunAdapterHelpers'
+
+export function toInstrumentRunRows(
+  template: InstrumentRunTemplate | InstrumentRunTemplateData
+): InstrumentRunRowsAdapterResult {
+  const data = getTemplateData(template, 'instrument-run')
+  validateInstrumentRunData(data)
+  const methods = new Map(data.methods.map(method => [method.id, method]))
+  return [...data.items]
+    .sort((a, b) => a.order - b.order)
+    .map(item => {
+      const method = methods.get(item.methodId)
+      return {
+        id: item.id,
+        order: item.order,
+        kind: item.kind,
+        sampleId: item.sampleId,
+        name: item.name ?? item.sampleId ?? item.kind,
+        method: method?.name ?? item.methodId,
+        vial: item.vial,
+        plateId: item.plateId,
+        wellId: item.wellId,
+        injectionVolume: item.injectionVolume,
+        expectedDurationMin: item.expectedDurationMin,
+        status: item.status,
+        instrument: data.instrument ?? method?.instrument,
+        ...(item.metadata ?? {}),
+      }
+    })
+}
+
+export function toInstrumentRunColumns(): InstrumentRunColumnsAdapterResult {
+  return [
+    { key: 'order', label: 'Order', sortable: true, align: 'right' },
+    { key: 'kind', label: 'Kind', sortable: true },
+    { key: 'sampleId', label: 'Sample ID', sortable: true },
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'method', label: 'Method', sortable: true },
+    { key: 'vial', label: 'Vial', sortable: true },
+    { key: 'wellId', label: 'Well', sortable: true },
+    { key: 'injectionVolume', label: 'Injection', sortable: true, align: 'right' },
+    { key: 'expectedDurationMin', label: 'Duration', sortable: true, align: 'right' },
+    { key: 'status', label: 'Status', sortable: true },
+    { key: 'instrument', label: 'Instrument', sortable: true },
+  ]
+}
+
+export function toInstrumentRunDataFrame(
+  template: InstrumentRunTemplate | InstrumentRunTemplateData
+): InstrumentRunDataFrameAdapterResult {
+  return {
+    data: toInstrumentRunRows(template),
+    columns: toInstrumentRunColumns(),
+    rowKey: 'id',
+  }
+}
+
+/** Convert an instrument-run template into ExperimentTimeline protocol steps for acquisition queue previews. */
+export function toInstrumentRunSteps(
+  template: InstrumentRunTemplate | InstrumentRunTemplateData
+): InstrumentRunStepsAdapterResult {
+  const data = getTemplateData(template, 'instrument-run')
+  validateInstrumentRunData(data)
+  const methods = new Map(data.methods.map(method => [method.id, method]))
+  return [...data.items]
+    .sort((a, b) => a.order - b.order)
+    .map((item): ProtocolStep => {
+      const method = methods.get(item.methodId)
+      const name = item.name ?? item.sampleId ?? item.kind
+      return {
+        id: item.id,
+        type: instrumentRunStepType(item.kind),
+        name,
+        description: [
+          item.kind,
+          method?.name,
+          item.vial ? `Vial ${item.vial}` : undefined,
+          item.wellId ? `Well ${item.wellId}` : undefined,
+        ]
+          .filter(Boolean)
+          .join(' / '),
+        duration: item.expectedDurationMin,
+        status: instrumentRunStepStatus(item.status),
+        parameters: {
+          kind: item.kind,
+          sampleId: item.sampleId,
+          methodId: item.methodId,
+          method: method?.name,
+          vial: item.vial,
+          plateId: item.plateId,
+          wellId: item.wellId,
+          injectionVolume: item.injectionVolume,
+          instrument: data.instrument ?? method?.instrument,
+        },
+        order: item.order,
+      }
+    })
+}
+
+/** Convert an instrument-run template into readonly ScheduleCalendar events ordered by run queue timing. */
+export function toInstrumentRunScheduleEvents(
+  template: InstrumentRunTemplate | InstrumentRunTemplateData
+): InstrumentRunScheduleEventsAdapterResult {
+  const data = getTemplateData(template, 'instrument-run')
+  validateInstrumentRunData(data)
+  const methods = new Map(data.methods.map(method => [method.id, method]))
+  let cursor = dateFromMetadata(data.metadata, ['scheduledStart', 'runStart', 'start', 'startedAt'])
+    ?? new Date('2024-01-01T08:00:00.000Z')
+
+  return [...data.items]
+    .sort((a, b) => a.order - b.order)
+    .map((item): ScheduleEvent => {
+      const method = methods.get(item.methodId)
+      const start = dateFromMetadata(item.metadata, ['scheduledStart', 'start', 'startedAt']) ?? cursor
+      const end = dateFromMetadata(item.metadata, ['scheduledEnd', 'end', 'completedAt'])
+        ?? addMinutes(start, Math.max(item.expectedDurationMin ?? 10, 1))
+      cursor = end
+
+      return {
+        id: item.id,
+        title: item.name ?? item.sampleId ?? item.kind,
+        start: start.toISOString(),
+        end: end.toISOString(),
+        color: instrumentRunScheduleColor(item.kind),
+        status: instrumentRunScheduleStatus(item.status),
+        draggable: false,
+        resizable: false,
+        metadata: {
+          kind: item.kind,
+          sampleId: item.sampleId,
+          methodId: item.methodId,
+          method: method?.name,
+          vial: item.vial,
+          plateId: item.plateId,
+          wellId: item.wellId,
+          injectionVolume: item.injectionVolume,
+          instrument: data.instrument ?? method?.instrument,
+        },
+      }
+    })
+}

package/src/templates/instrumentRunBuilder.ts

@@ -0,0 +1,97 @@
+import { idFromName } from './builderIdUtils'
+import {
+  normalizeInstrumentMethod,
+  normalizeInstrumentRunItem,
+} from './runNormalizers'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateInstrumentRunData } from './templateValidators'
+import type {
+  CreateInstrumentRunTemplateOptions,
+  InstrumentRunItem,
+  InstrumentRunTemplate,
+  InstrumentRunTemplateData,
+} from './types'
+
+export function createInstrumentRunTemplate(
+  options: CreateInstrumentRunTemplateOptions
+): InstrumentRunTemplate {
+  const method = typeof options.method === 'string' || options.method === undefined
+    ? {
+        id: idFromName(options.method ?? 'Default method', 'method-1'),
+        name: options.method ?? 'Default method',
+        instrument: options.instrument,
+        metadata: {},
+      }
+    : normalizeInstrumentMethod(options.method, options.instrument)
+  const items: InstrumentRunItem[] = []
+  let order = 1
+
+  if (options.includeBlanks !== false) {
+    items.push({
+      id: 'blank-start',
+      order,
+      kind: 'blank',
+      name: 'Blank start',
+      methodId: method.id,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  if (options.includeQc !== false) {
+    items.push({
+      id: 'qc-start',
+      order,
+      kind: 'qc',
+      name: 'QC start',
+      methodId: method.id,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  for (const [index, item] of options.items.entries()) {
+    if (typeof item !== 'string') {
+      const normalized = normalizeInstrumentRunItem(item, method.id, order, index)
+      items.push(normalized)
+      order = Math.max(order, normalized.order + 1)
+      continue
+    }
+    const sampleId = idFromName(item, `sample-${index + 1}`)
+    items.push({
+      id: `${sampleId}-run`,
+      order,
+      kind: 'sample',
+      sampleId,
+      name: item,
+      methodId: method.id,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  if (options.includeQc !== false) {
+    items.push({
+      id: 'qc-end',
+      order,
+      kind: 'qc',
+      name: 'QC end',
+      methodId: method.id,
+      status: 'planned',
+      metadata: {},
+    })
+  }
+
+  const data: InstrumentRunTemplateData = {
+    runId: 'run-1',
+    instrument: options.instrument,
+    methods: [method],
+    items,
+    metadata: options.metadata ?? {},
+  }
+  validateInstrumentRunData(data)
+  return createTemplateEnvelope('instrument-run', data, options.metadata ?? {})
+}

package/src/templates/lcmsBatchCollectionBuilder.ts

@@ -0,0 +1,38 @@
+import { createAssayMatrixTemplate } from './assayMatrixBuilder'
+import { createInstrumentRunTemplate } from './instrumentRunBuilder'
+import { createSampleSheetTemplate } from './sampleSheetBuilder'
+import { presetSampleRecords } from './sampleNormalizers'
+import { createTemplateCollection } from './templateEnvelopes'
+import type {
+  CreateLcmsBatchCollectionOptions,
+  TemplateCollectionEnvelope,
+} from './types'
+
+export function createLcmsBatchCollection(
+  options: CreateLcmsBatchCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['S001', 'S002'])
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const instrumentRun = createInstrumentRunTemplate({
+    items: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name ?? sample.sampleId,
+    })),
+    method: options.method ?? 'Default method',
+    instrument: options.instrument ?? 'LC-MS',
+    includeQc: options.includeQc,
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: options.features ?? ['Glucose', 'Lactate'],
+  })
+  return createTemplateCollection(
+    [sampleSheet, instrumentRun, assayMatrix],
+    { preset: 'lcms-batch', ...(options.metadata ?? {}) }
+  )
+}

package/src/templates/lookup.ts

@@ -0,0 +1,18 @@
+/** Normalize human-facing template lookup terms so spaces, hyphens, and underscores behave the same. */
+export function normalizeTemplateLookupKey(value: string): string {
+  return value.trim().toLowerCase().replace(/[\s_-]+/g, '-')
+}
+
+export function templateIdentifierMatches(query: string, identifiers: readonly string[]): boolean {
+  const normalizedQuery = normalizeTemplateLookupKey(query)
+  return identifiers.some(value => normalizeTemplateLookupKey(value) === normalizedQuery)
+}
+
+export function templateSearchMatches(query: string, values: readonly string[]): boolean {
+  const lowerQuery = query.trim().toLowerCase()
+  const normalizedQuery = normalizeTemplateLookupKey(query)
+  return values.some(value =>
+    value.toLowerCase().includes(lowerQuery)
+    || normalizeTemplateLookupKey(value).includes(normalizedQuery),
+  )
+}

package/src/templates/packs.ts

@@ -0,0 +1,162 @@
+import { bioTemplateCatalog } from './catalog'
+import type { TemplateId, TemplatePackId } from './types'
+
+import { templateIdentifierMatches, templateSearchMatches } from './lookup'
+
+export interface BioTemplatePackEntry {
+  name: TemplatePackId
+  label: string
+  category: 'bio-template-pack'
+  purpose: string
+  templates: readonly TemplateId[]
+  aliases: readonly string[]
+  frontend_adapters: readonly string[]
+  components: readonly string[]
+  add_command: string
+  docs_command: string
+}
+
+interface BioTemplatePackDefinition {
+  name: TemplatePackId
+  label: string
+  purpose: string
+  templates: readonly TemplateId[]
+  aliases: readonly string[]
+}
+
+const templateInfoById = new Map(
+  bioTemplateCatalog.map(entry => [entry.template_id, entry]),
+)
+
+function collectTemplateField(
+  templateIds: readonly TemplateId[],
+  field: 'frontend_adapters' | 'components',
+): readonly string[] {
+  const values: string[] = []
+  for (const templateId of templateIds) {
+    const entry = templateInfoById.get(templateId)
+    if (!entry) {
+      throw new Error(`Unknown bio template in pack catalog: ${templateId}`)
+    }
+    for (const value of entry[field]) {
+      if (!values.includes(value)) {
+        values.push(value)
+      }
+    }
+  }
+  return values
+}
+
+function createPack(definition: BioTemplatePackDefinition): BioTemplatePackEntry {
+  return {
+    ...definition,
+    category: 'bio-template-pack',
+    frontend_adapters: collectTemplateField(definition.templates, 'frontend_adapters'),
+    components: collectTemplateField(definition.templates, 'components'),
+    add_command: `mint add data-template-pack ${definition.name} --page`,
+    docs_command: `mint docs template-pack ${definition.name}`,
+  }
+}
+
+const bioTemplatePackDefinitions = [
+  {
+    name: 'cell-culture-screen',
+    label: 'Cell culture screen',
+    purpose: 'Plate layout, sample metadata, sample prep, reagents, protocol, dose-response, and flow-panel setup.',
+    templates: [
+      'sample-sheet',
+      'sample-prep',
+      'plate-map',
+      'reagent-list',
+      'protocol-steps',
+      'dose-response',
+      'flow-cytometry-panel',
+    ],
+    aliases: ['cell culture', 'screen', 'drug screen', 'plate screen'],
+  },
+  {
+    name: 'omics-assay',
+    label: 'Omics assay',
+    purpose: 'Sample metadata, sample prep, reagents, protocol, instrument run queue, calibration curve, and measurement matrix.',
+    templates: [
+      'sample-sheet',
+      'sample-prep',
+      'reagent-list',
+      'protocol-steps',
+      'instrument-run',
+      'calibration-curve',
+      'assay-matrix',
+    ],
+    aliases: [
+      'omics',
+      'metabolomics',
+      'metabolism',
+      'metabolite profiling',
+      'proteomics',
+      'assay matrix',
+      'lcms',
+      'standard curve',
+    ],
+  },
+  {
+    name: 'longitudinal-study',
+    label: 'Longitudinal study',
+    purpose: 'Sample metadata, time-course schedule, protocol, and measurement matrix.',
+    templates: [
+      'sample-sheet',
+      'time-course',
+      'protocol-steps',
+      'assay-matrix',
+    ],
+    aliases: ['time series', 'time-course study', 'kinetics', 'longitudinal'],
+  },
+  {
+    name: 'molecular-assay',
+    label: 'Molecular assay',
+    purpose: 'Sample metadata, sample prep, reagents, protocol, instrument run queue, calibration curve, and qPCR/ddPCR plate setup.',
+    templates: [
+      'sample-sheet',
+      'sample-prep',
+      'reagent-list',
+      'protocol-steps',
+      'instrument-run',
+      'calibration-curve',
+      'qpcr-plate',
+    ],
+    aliases: ['molecular', 'qpcr', 'qPCR', 'gene expression', 'rt-qpcr', 'ddpcr'],
+  },
+] as const satisfies readonly BioTemplatePackDefinition[]
+
+export const bioTemplatePacks = bioTemplatePackDefinitions.map(createPack) as readonly BioTemplatePackEntry[]
+
+export function listBioTemplatePacks(): readonly BioTemplatePackEntry[] {
+  return bioTemplatePacks
+}
+
+export function getBioTemplatePackInfo(name: string): BioTemplatePackEntry | undefined {
+  return bioTemplatePacks.find(entry => {
+    const identifiers = [
+      entry.name,
+      entry.label,
+      ...entry.aliases,
+    ]
+    return templateIdentifierMatches(name, identifiers)
+  })
+}
+
+export function searchBioTemplatePacks(query: string): readonly BioTemplatePackEntry[] {
+  const normalized = query.trim().toLowerCase()
+  if (!normalized) return bioTemplatePacks
+
+  return bioTemplatePacks.filter(entry => templateSearchMatches(normalized, [
+    entry.name,
+    entry.label,
+    entry.purpose,
+    entry.add_command,
+    entry.docs_command,
+    ...entry.templates,
+    ...entry.aliases,
+    ...entry.frontend_adapters,
+    ...entry.components,
+  ]))
+}

package/src/templates/plateGeometry.ts

@@ -0,0 +1,62 @@
+import type { WellPlateFormat } from '../types'
+
+const PLATE_DIMENSIONS: Record<number, readonly [number, number]> = {
+  6: [2, 3],
+  12: [3, 4],
+  24: [4, 6],
+  48: [6, 8],
+  54: [6, 9],
+  96: [8, 12],
+  384: [16, 24],
+}
+
+export function wellIdsForFormat(format: number): string[] {
+  const dimensions = PLATE_DIMENSIONS[format]
+  if (!dimensions) {
+    throw new Error(`Unsupported plate format '${format}'.`)
+  }
+  const [rows, cols] = dimensions
+  return Array.from({ length: rows }, (_, row) =>
+    Array.from({ length: cols }, (_col, col) => `${rowLabel(row)}${col + 1}`)
+  ).flat()
+}
+
+export function assertWellInFormat(wellId: string, format: number): void {
+  const dimensions = PLATE_DIMENSIONS[format]
+  if (!dimensions) {
+    throw new Error(`Unsupported plate format '${format}'.`)
+  }
+  const match = /^([A-Z]+)([1-9][0-9]*)$/.exec(wellId.toUpperCase())
+  if (!match) {
+    throw new Error(`Invalid well id '${wellId}'.`)
+  }
+  const row = rowIndex(match[1])
+  const col = Number(match[2]) - 1
+  const [rows, cols] = dimensions
+  if (row < 0 || col < 0 || row >= rows || col >= cols) {
+    throw new Error(`Well '${wellId}' is outside a ${format}-well plate.`)
+  }
+}
+
+export function readPlateFormat(value: unknown, fallback: WellPlateFormat): WellPlateFormat {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number(value)
+      : Number.NaN
+  return parsed in PLATE_DIMENSIONS ? (parsed as WellPlateFormat) : fallback
+}
+
+function rowLabel(index: number): string {
+  let label = ''
+  let current = index
+  while (true) {
+    label = String.fromCharCode(65 + (current % 26)) + label
+    current = Math.floor(current / 26) - 1
+    if (current < 0) return label
+  }
+}
+
+function rowIndex(label: string): number {
+  return [...label].reduce((value, char) => value * 26 + char.charCodeAt(0) - 64, 0) - 1
+}

package/src/templates/plateMapAdapters.ts

@@ -0,0 +1,36 @@
+import type {
+  PlateMapEditorState,
+} from '../types'
+import { getTemplateData } from './templateEnvelopes'
+import { validatePlateMapData } from './templateValidators'
+import type {
+  PlateMapEditorAdapterResult,
+  PlateMapTemplate,
+  PlateMapTemplateData,
+  WellMapAdapterResult,
+} from './types'
+
+export function toPlateMapEditorState(
+  template: PlateMapTemplate | PlateMapTemplateData
+): PlateMapEditorAdapterResult {
+  const data = getTemplateData(template, 'plate-map')
+  validatePlateMapData(data)
+  const activePlateId = data.activePlateId ?? data.plates[0].id
+  return {
+    plates: data.plates,
+    activePlateId,
+    samples: data.samples,
+    selectedWells: data.selectedWells ?? [],
+    activeSampleId: data.activeSampleId,
+  } satisfies PlateMapEditorState
+}
+
+export function toWellPlateWells(
+  template: PlateMapTemplate | PlateMapTemplateData,
+  plateId?: string
+): WellMapAdapterResult {
+  const state = toPlateMapEditorState(template)
+  const plate = state.plates.find(candidate => candidate.id === (plateId ?? state.activePlateId))
+    ?? state.plates[0]
+  return plate.wells
+}

package/src/templates/plateMapBuilder.ts

@@ -0,0 +1,43 @@
+import { DEFAULT_SAMPLE_COLORS } from './builderDefaults'
+import { sampleIdFromName } from './builderIdUtils'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import type {
+  CreatePlateMapTemplateOptions,
+  PlateMapTemplate,
+  TemplateSample,
+} from './types'
+
+export function createPlateMapTemplate(
+  options: CreatePlateMapTemplateOptions = {}
+): PlateMapTemplate {
+  const {
+    id = 'plate-1',
+    name = 'Plate 1',
+    format = 96,
+    samples = [],
+    metadata = {},
+  } = options
+
+  const sampleDefinitions = samples.map((sample, index): TemplateSample => {
+    if (typeof sample !== 'string') return sample
+    return {
+      id: sampleIdFromName(sample, index),
+      name: sample,
+      color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+    }
+  })
+
+  return createTemplateEnvelope('plate-map', {
+    plates: [
+      {
+        id,
+        name,
+        format,
+        wells: {},
+      },
+    ],
+    samples: sampleDefinitions,
+    activePlateId: id,
+    selectedWells: [],
+  }, metadata)
+}