@morscherlab/mint-sdk 1.0.0-rc.2 → 1.0.0-rc.5

package/src/templates/templateControlSchemas.ts

@@ -0,0 +1,320 @@
+import {
+  CONCENTRATION_UNITS,
+  ICONS,
+  PLATE_FORMAT_OPTIONS,
+} from './controlSchemaConstants'
+import type {
+  BioTemplateControlSchema,
+} from './controlSchemaTypes'
+import type {
+  TemplateId,
+} from './types'
+
+export const templateControlSchemas = {
+  'plate-map': {
+    plateName: {
+      label: 'Plate name',
+      default: 'Plate 1',
+      section: 'layout',
+      sectionLabel: 'Layout',
+      sectionSubtitle: 'Plate geometry',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    plateFormat: {
+      label: 'Format',
+      default: 96,
+      options: PLATE_FORMAT_OPTIONS,
+      section: 'layout',
+      view: 'design',
+    },
+    sampleNames: {
+      type: 'tags',
+      label: 'Samples',
+      default: ['Control', 'Treatment'],
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Groups and legend',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+  },
+  'sample-sheet': {
+    sampleCount: {
+      type: 'number',
+      label: 'Sample count',
+      default: 2,
+      min: 1,
+      max: 10000,
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Metadata table',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    includeGroups: {
+      label: 'Include groups',
+      default: true,
+      section: 'samples',
+      view: 'design',
+    },
+    includeBatch: {
+      label: 'Include batch',
+      default: false,
+      section: 'columns',
+      sectionLabel: 'Columns',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+  },
+  'sample-prep': {
+    prepType: {
+      label: 'Prep type',
+      default: 'extraction',
+      options: ['extraction', 'dilution', 'normalization', 'transfer', 'quench', 'custom'],
+      section: 'protocol',
+      sectionLabel: 'Protocol',
+      sectionSubtitle: 'Prep workflow',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#f97316', iconBg: '#ffedd5' },
+    },
+    volumeUnit: {
+      label: 'Volume unit',
+      default: 'uL',
+      options: ['uL', 'mL'],
+      section: 'protocol',
+      view: 'design',
+    },
+    outputVolume: {
+      type: 'number',
+      label: 'Output volume',
+      default: 50,
+      min: 0,
+      section: 'protocol',
+      view: 'design',
+    },
+  },
+  'dose-response': {
+    unit: {
+      label: 'Dose unit',
+      default: 'uM',
+      options: CONCENTRATION_UNITS,
+      section: 'dose',
+      sectionLabel: 'Dose Design',
+      sectionSubtitle: 'Concentration series',
+      view: 'design',
+      sidebar: { icon: ICONS.dose, iconColor: '#8b5cf6', iconBg: '#ede9fe' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 24,
+      section: 'dose',
+      view: 'design',
+    },
+    includePlateLayout: {
+      label: 'Create plate layout',
+      default: true,
+      section: 'layout',
+      sectionLabel: 'Layout',
+      sectionSubtitle: 'Well assignment',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'calibration-curve': {
+    analyte: {
+      label: 'Analyte',
+      default: 'Analyte',
+      section: 'standards',
+      sectionLabel: 'Standards',
+      sectionSubtitle: 'Curve setup',
+      view: 'analysis',
+      sidebar: { icon: ICONS.dose, iconColor: '#8b5cf6', iconBg: '#ede9fe' },
+    },
+    model: {
+      label: 'Model',
+      default: 'linear',
+      options: ['linear', 'linear-weighted-1-x', 'linear-weighted-1-x2', 'quadratic', 'four-parameter-logistic'],
+      section: 'fit',
+      sectionLabel: 'Fit',
+      view: 'analysis',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    minRSquared: {
+      type: 'number',
+      label: 'Minimum R squared',
+      default: 0.99,
+      min: 0,
+      max: 1,
+      props: { step: 0.001 },
+      section: 'fit',
+      view: 'analysis',
+    },
+  },
+  'time-course': {
+    timeUnit: {
+      label: 'Time unit',
+      default: 'hour',
+      options: ['second', 'minute', 'hour', 'day', 'week'],
+      section: 'schedule',
+      sectionLabel: 'Schedule',
+      sectionSubtitle: 'Sampling timeline',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 24,
+      section: 'samples',
+      sectionLabel: 'Samples',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+  },
+  'protocol-steps': {
+    defaultDuration: {
+      type: 'number',
+      label: 'Default duration',
+      default: 30,
+      min: 0,
+      section: 'protocol',
+      sectionLabel: 'Protocol',
+      sectionSubtitle: 'Step defaults',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#f97316', iconBg: '#ffedd5' },
+      props: { suffix: 'min' },
+    },
+    editable: {
+      label: 'Editable timeline',
+      default: true,
+      section: 'protocol',
+      view: 'design',
+    },
+  },
+  'assay-matrix': {
+    featureType: {
+      label: 'Feature type',
+      default: 'metabolite',
+      options: ['metabolite', 'protein', 'gene', 'cell', 'compound', 'readout', 'other'],
+      section: 'features',
+      sectionLabel: 'Features',
+      sectionSubtitle: 'Measurement matrix',
+      view: 'analysis',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    normalizeValues: {
+      label: 'Normalize values',
+      default: false,
+      section: 'analysis',
+      sectionLabel: 'Analysis',
+      view: 'analysis',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'reagent-list': {
+    reagentKind: {
+      label: 'Reagent kind',
+      default: 'reagent',
+      options: ['compound', 'antibody', 'primer', 'enzyme', 'buffer', 'media', 'kit', 'reagent', 'other'],
+      section: 'inventory',
+      sectionLabel: 'Inventory',
+      sectionSubtitle: 'Reagent metadata',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    trackStock: {
+      label: 'Track stock level',
+      default: true,
+      section: 'inventory',
+      view: 'design',
+    },
+  },
+  'flow-cytometry-panel': {
+    markers: {
+      type: 'tags',
+      label: 'Markers',
+      default: ['CD3', 'CD4', 'CD8'],
+      section: 'panel',
+      sectionLabel: 'Panel',
+      sectionSubtitle: 'Markers and controls',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    instrument: {
+      label: 'Instrument',
+      default: 'Flow cytometer',
+      section: 'panel',
+      sectionLabel: 'Panel',
+      sectionSubtitle: 'Markers and controls',
+      view: 'design',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    includeDefaultControls: {
+      label: 'Default controls',
+      default: true,
+      section: 'panel',
+      view: 'design',
+    },
+  },
+  'instrument-run': {
+    instrument: {
+      label: 'Instrument',
+      default: 'LC-MS',
+      options: ['LC-MS', 'GC-MS', 'Orbitrap', 'Triple quadrupole', 'Plate reader', 'Other'],
+      section: 'acquisition',
+      sectionLabel: 'Acquisition',
+      sectionSubtitle: 'Run queue',
+      view: 'run',
+      sidebar: { icon: ICONS.run, iconColor: '#ef4444', iconBg: '#fee2e2' },
+    },
+    method: {
+      label: 'Method',
+      default: 'Default method',
+      section: 'acquisition',
+      view: 'run',
+    },
+    includeQc: {
+      label: 'Include QC',
+      default: true,
+      section: 'quality',
+      sectionLabel: 'Quality Control',
+      view: 'run',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'qpcr-plate': {
+    chemistry: {
+      label: 'Chemistry',
+      default: 'sybr',
+      options: ['sybr', 'taqman', 'probe', 'evagreen', 'other'],
+      section: 'assay',
+      sectionLabel: 'Assay',
+      sectionSubtitle: 'qPCR setup',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 12,
+      section: 'assay',
+      view: 'design',
+    },
+    includeNoTemplateControls: {
+      label: 'No-template controls',
+      default: true,
+      section: 'controls',
+      sectionLabel: 'Controls',
+      view: 'design',
+      sidebar: { icon: ICONS.settings, iconColor: '#8b5cf6', iconBg: '#ede9fe', defaultOpen: false },
+    },
+  },
+} satisfies Record<TemplateId, BioTemplateControlSchema>

package/src/templates/templateCreateOptions.ts

@@ -0,0 +1,208 @@
+import type { WellPlateFormat } from '../types'
+import type {
+  AssayFeature,
+  AssaySample,
+  CalibrationAcceptanceInput,
+  CalibrationModel,
+  CalibrationPointInput,
+  CompoundDoseSeries,
+  ControlDefinition,
+  FlowPanelControl,
+  FlowPanelMarker,
+  InstrumentMethodInput,
+  InstrumentRunItemInput,
+  PlateMapTemplate,
+  PlateMapTemplateData,
+  ProtocolStepRecord,
+  ReagentTemplateInput,
+  SampleColumn,
+  SampleGroupDefinition,
+  SamplePrepStepInput,
+  SamplePrepStepType,
+  SampleRecord,
+  TemplateSample,
+  TimeCourseCondition,
+  TimePoint,
+  TimeUnit,
+} from './types'
+import type {
+  QpcrChemistry,
+  QpcrSample,
+  QpcrTarget,
+} from './templateQpcrTypes'
+
+export interface CreateBioTemplatePackCollectionOptions {
+  metadata?: Record<string, unknown>
+}
+
+export interface CreatePlateMapTemplateOptions {
+  name?: string
+  id?: string
+  format?: WellPlateFormat
+  samples?: Array<string | TemplateSample>
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateSampleSheetTemplateOptions {
+  samples: SampleRecord[]
+  columns?: SampleColumn[]
+  groups?: SampleGroupDefinition[]
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateSamplePrepTemplateOptions {
+  samples: Array<string | SamplePrepStepInput>
+  prepType?: SamplePrepStepType
+  protocolName?: string
+  volumeUnit?: string
+  inputVolume?: number
+  outputVolume?: number
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateDoseResponseTemplateOptions {
+  compounds: Record<string, number[]> | CompoundDoseSeries[]
+  unit: string
+  replicates?: number
+  controls?: ControlDefinition[]
+  layout?: PlateMapTemplate | PlateMapTemplateData
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateCalibrationCurveTemplateOptions {
+  concentrations: Array<number | CalibrationPointInput>
+  analyte?: string
+  unit?: string
+  responseUnit?: string
+  model?: CalibrationModel
+  includeBlank?: boolean
+  includeQc?: boolean
+  acceptance?: CalibrationAcceptanceInput
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateTimeCourseTemplateOptions {
+  timepoints: Array<number | TimePoint>
+  unit: TimeUnit
+  conditions: Array<string | TimeCourseCondition>
+  replicates?: number
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateAssayMatrixTemplateOptions {
+  samples: Array<string | AssaySample>
+  features: Array<string | AssayFeature>
+  values?: Record<string, Record<string, number | null | undefined>>
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateProtocolStepsTemplateOptions {
+  steps: Array<string | (Partial<ProtocolStepRecord> & { name: string })>
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateReagentListTemplateOptions {
+  reagents: Array<string | ReagentTemplateInput>
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateFlowCytometryPanelTemplateOptions {
+  markers: Array<string | (Partial<FlowPanelMarker> & { marker: string })>
+  controls?: Array<string | (Partial<FlowPanelControl> & { name: string })>
+  instrument?: string
+  includeDefaultControls?: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateInstrumentRunTemplateOptions {
+  items: Array<string | InstrumentRunItemInput>
+  method?: string | InstrumentMethodInput
+  instrument?: string
+  includeBlanks?: boolean
+  includeQc?: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateQpcrPlateTemplateOptions {
+  samples: Array<string | QpcrSample>
+  targets: Array<string | QpcrTarget>
+  format?: WellPlateFormat
+  replicates?: number
+  includeNoTemplateControls?: boolean
+  instrument?: string
+  chemistry?: QpcrChemistry
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateWellPlateScreenCollectionOptions {
+  samples?: Array<string | SampleRecord>
+  compounds?: Record<string, number[]> | CompoundDoseSeries[]
+  unit?: string
+  replicates?: number
+  plateName?: string
+  plateFormat?: WellPlateFormat
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateQpcrExpressionCollectionOptions {
+  samples?: Array<string | SampleRecord>
+  targets?: Array<string | QpcrTarget>
+  chemistry?: QpcrChemistry
+  includeNoTemplateControls?: boolean
+  format?: WellPlateFormat
+  replicates?: number
+  instrument?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateLcmsBatchCollectionOptions {
+  samples?: Array<string | SampleRecord>
+  features?: Array<string | AssayFeature>
+  instrument?: string
+  method?: string | InstrumentMethodInput
+  includeQc?: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateTargetedMetabolomicsCollectionOptions {
+  samples?: Array<string | SampleRecord>
+  metabolites?: Array<string | AssayFeature>
+  internalStandards?: Array<string | ReagentTemplateInput>
+  standardConcentrations?: number[]
+  concentrationUnit?: string
+  responseUnit?: string
+  calibrationAnalyte?: string
+  instrument?: string
+  method?: string | InstrumentMethodInput
+  prepType?: SamplePrepStepType
+  outputVolume?: number
+  includeQc?: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateElisaAssayCollectionOptions {
+  samples?: Array<string | SampleRecord>
+  analyte?: string
+  standardConcentrations?: number[]
+  unit?: string
+  responseUnit?: string
+  plateName?: string
+  plateFormat?: WellPlateFormat
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateFlowCytometryAssayCollectionOptions {
+  samples?: Array<string | SampleRecord>
+  markers?: CreateFlowCytometryPanelTemplateOptions['markers']
+  features?: Array<string | AssayFeature>
+  instrument?: string
+  includeDefaultControls?: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateWesternBlotAssayCollectionOptions {
+  samples?: Array<string | SampleRecord>
+  targets?: Array<string | AssayFeature>
+  loadingControl?: string
+  metadata?: Record<string, unknown>
+}

package/src/templates/templateEnvelopes.ts

@@ -0,0 +1,137 @@
+import type {
+  BioTemplateEnvelope,
+  TemplateCollection,
+  TemplateCollectionEnvelope,
+  TemplateId,
+} from './types'
+import { isRecord } from './builderReadUtils'
+
+export const TEMPLATE_COLLECTION_KEY = 'templates'
+
+export function createTemplateEnvelope<TData>(
+  templateId: TemplateId,
+  data: TData,
+  metadata: Record<string, unknown> = {},
+  templateVersion = '1.0'
+): BioTemplateEnvelope<TData> {
+  return {
+    template_id: templateId,
+    template_version: templateVersion,
+    kind: 'experiment-design',
+    data,
+    metadata,
+  }
+}
+
+export function createTemplateCollection(
+  templates: Array<BioTemplateEnvelope<unknown>>,
+  metadata?: Record<string, unknown>
+): TemplateCollectionEnvelope {
+  const collection: TemplateCollection = {}
+  for (const template of templates) {
+    assertGenericTemplateEnvelope(template)
+    const templateId = template.template_id
+    if (collection[templateId]) {
+      throw new Error(`Duplicate template_id '${templateId}' in template collection.`)
+    }
+    collection[templateId] = template
+  }
+
+  return metadata === undefined
+    ? { [TEMPLATE_COLLECTION_KEY]: collection }
+    : { [TEMPLATE_COLLECTION_KEY]: collection, metadata }
+}
+
+export function extractTemplateCollection(value: unknown): TemplateCollection {
+  if (isEnvelope<unknown>(value)) {
+    assertGenericTemplateEnvelope(value)
+    return { [value.template_id]: value }
+  }
+  if (!isRecord(value)) {
+    throw new Error('Template collection payload must be an object.')
+  }
+
+  const rawCollection = value[TEMPLATE_COLLECTION_KEY]
+  if (rawCollection === undefined) {
+    return {}
+  }
+  if (!isRecord(rawCollection)) {
+    throw new Error('Template collection must be an object.')
+  }
+
+  const collection: TemplateCollection = {}
+  for (const [templateId, template] of Object.entries(rawCollection)) {
+    assertGenericTemplateEnvelope(template)
+    if (template.template_id !== templateId) {
+      throw new Error(
+        `Template collection key '${templateId}' does not match envelope template_id '${template.template_id}'.`
+      )
+    }
+    collection[templateId] = template
+  }
+  return collection
+}
+
+export function ensureTemplateFromCollection<TTemplate extends BioTemplateEnvelope<unknown>>(
+  value: unknown,
+  templateId: TemplateId | string
+): TTemplate {
+  const collection = extractTemplateCollection(value)
+  const template = collection[templateId]
+  if (!template) {
+    throw new Error(`Template '${templateId}' was not found in template collection.`)
+  }
+  assertTemplateEnvelope(template, templateId)
+  return template as TTemplate
+}
+
+export function assertTemplateEnvelope<TData>(
+  value: unknown,
+  templateId: TemplateId | string
+): asserts value is BioTemplateEnvelope<TData> {
+  assertGenericTemplateEnvelope(value)
+  if (value.template_id !== templateId) {
+    throw new Error(`Expected template_id '${templateId}', got '${String(value.template_id)}'.`)
+  }
+}
+
+export function ensureTemplateEnvelope<TTemplate extends BioTemplateEnvelope<unknown>>(
+  value: unknown,
+  templateId: TemplateId | string
+): TTemplate {
+  assertTemplateEnvelope(value, templateId)
+  return value as TTemplate
+}
+
+export function getTemplateData<TData>(
+  template: BioTemplateEnvelope<TData> | TData,
+  templateId?: TemplateId | string
+): TData {
+  if (isEnvelope<TData>(template)) {
+    if (templateId) assertTemplateEnvelope<TData>(template, templateId)
+    return template.data
+  }
+  return template
+}
+
+function assertGenericTemplateEnvelope(value: unknown): asserts value is BioTemplateEnvelope<unknown> {
+  if (!isRecord(value)) {
+    throw new Error('Template envelope must be an object.')
+  }
+  if (typeof value.template_id !== 'string' || value.template_id.length === 0) {
+    throw new Error('Template envelope requires a template_id string.')
+  }
+  if (typeof value.template_version !== 'string' || value.template_version.length === 0) {
+    throw new Error('Template envelope requires a template_version string.')
+  }
+  if (!isRecord(value.data)) {
+    throw new Error('Template envelope data must be an object.')
+  }
+  if ('metadata' in value && !isRecord(value.metadata)) {
+    throw new Error('Template envelope metadata must be an object.')
+  }
+}
+
+function isEnvelope<TData>(value: unknown): value is BioTemplateEnvelope<TData> {
+  return isRecord(value) && 'template_id' in value && 'data' in value
+}

package/src/templates/templatePackCollectionBuilder.ts

@@ -0,0 +1,23 @@
+import { getBioTemplatePackInfo } from './packs'
+import { createDefaultBioTemplate } from './defaultBioTemplateBuilder'
+import { createTemplateCollection } from './templateEnvelopes'
+import type {
+  CreateBioTemplatePackCollectionOptions,
+  TemplateCollectionEnvelope,
+  TemplatePackId,
+} from './types'
+
+export function createBioTemplatePackCollection(
+  name: TemplatePackId | string,
+  options: CreateBioTemplatePackCollectionOptions = {},
+): TemplateCollectionEnvelope {
+  const pack = getBioTemplatePackInfo(name)
+  if (!pack) {
+    throw new Error(`Unknown template pack '${name}'.`)
+  }
+
+  return createTemplateCollection(
+    pack.templates.map(templateId => createDefaultBioTemplate(templateId)),
+    { pack: pack.name, ...(options.metadata ?? {}) },
+  )
+}