@apollo-annotation/common 0.1.11

package/README.md

@@ -0,0 +1 @@
+# apollo-mst

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@apollo-annotation/common",
+  "version": "0.1.11",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GMOD/Apollo3.git",
+    "directory": "packages/apollo-common"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@apollo-annotation/schemas": "^0.1.11",
+    "@gmod/gff": "1.2.0",
+    "@jbrowse/core": "^2.7.0",
+    "bson-objectid": "^2.0.4",
+    "tslib": "^2.3.1"
+  },
+  "peerDependencies": {
+    "@mui/material": "^5.11.14",
+    "@mui/x-data-grid": "^7.0.0",
+    "mobx": "^6.6.1",
+    "mobx-react": "^7.2.1",
+    "mobx-state-tree": "^5.1.7",
+    "prop-types": "^15.8.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rxjs": "^7.4.0",
+    "tss-react": "^4.6.1"
+  },
+  "devDependencies": {
+    "@apollo-annotation/mst": "^0.1.11",
+    "@nestjs/common": "^10.1.0",
+    "@nestjs/core": "^10.1.0",
+    "@types/node": "^18.14.2",
+    "mongoose": "^6.12.0",
+    "typescript": "^5.1.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/ApolloPlugin.ts

@@ -0,0 +1,13 @@
+import Plugin from '@jbrowse/core/Plugin'
+import PluginManager from '@jbrowse/core/PluginManager'
+
+export type ApolloPluginConstructor = new (...args: unknown[]) => ApolloPlugin
+
+export interface ApolloPluginManager {
+  addToExtensionPoint: PluginManager['addToExtensionPoint']
+}
+
+export abstract class ApolloPlugin extends Plugin {
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  apolloInstall(_pluginManager: ApolloPluginManager): void {}
+}

package/src/AssemblySpecificChange.ts

@@ -0,0 +1,468 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-condition */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-unsafe-call */
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+/* eslint-disable @typescript-eslint/restrict-template-expressions */
+import type { AnnotationFeatureSnapshot } from '@apollo-annotation/mst'
+import { FileDocument, RefSeqDocument } from '@apollo-annotation/schemas'
+import { GFF3Feature } from '@gmod/gff'
+import ObjectID from 'bson-objectid'
+
+import { Change, ChangeOptions, SerializedChange, isChange } from './Change'
+import { ServerDataStore } from './Operation'
+
+export interface SerializedAssemblySpecificChange extends SerializedChange {
+  assembly: string
+}
+
+export function isAssemblySpecificChange(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  thing: any,
+): thing is AssemblySpecificChange {
+  return (
+    isChange(thing) && (thing as AssemblySpecificChange).assembly !== undefined
+  )
+}
+
+export abstract class AssemblySpecificChange extends Change {
+  assembly: string
+
+  constructor(json: SerializedAssemblySpecificChange, options?: ChangeOptions) {
+    super(json, options)
+    this.assembly = json.assembly
+  }
+
+  async addRefSeqIntoDb(
+    fileDoc: FileDocument,
+    assembly: string,
+    backend: ServerDataStore,
+  ) {
+    const { logger } = this
+    const { filesService, refSeqChunkModel, refSeqModel, user } = backend
+    const { CHUNK_SIZE } = process.env
+    const customChunkSize = CHUNK_SIZE && Number(CHUNK_SIZE)
+    let chunkIndex = 0
+    let refSeqLen = 0
+    let refSeqDoc: RefSeqDocument | undefined
+    let fastaInfoStarted = fileDoc.type !== 'text/x-gff3'
+
+    // Read data from compressed file and parse the content
+    const sequenceStream = filesService.getFileStream(fileDoc)
+    let sequenceBuffer = ''
+    let incompleteLine = ''
+    let lastLineIsIncomplete = true
+    let parsingStarted = false
+    logger.debug?.('starting sequence stream')
+    for await (const data of sequenceStream) {
+      const chunk = data.toString()
+      lastLineIsIncomplete = !chunk.endsWith('\n')
+      // chunk is small enough that you can split the whole thing into lines without having to make it into smaller chunks first.
+      const lines = chunk.split(/\r?\n/)
+      if (incompleteLine) {
+        lines[0] = `${incompleteLine}${lines[0]}`
+        incompleteLine = ''
+      }
+      if (lastLineIsIncomplete) {
+        incompleteLine = lines.pop() || ''
+      }
+      for await (const line of lines) {
+        // In case of GFF3 file we start to read sequence after '##FASTA' is found
+        if (!fastaInfoStarted) {
+          if (line.trim() === '##FASTA') {
+            fastaInfoStarted = true
+          }
+          continue
+        }
+        const refSeqInfoLine = /^>\s*(\S+)\s*(.*)/.exec(line)
+        // Add new ref sequence info if we are reference seq info line
+        if (refSeqInfoLine) {
+          parsingStarted = true
+          logger.debug?.(
+            `Reference sequence information line "${refSeqInfoLine}"`,
+          )
+
+          // If there is sequence from previous reference sequence then we need to add it to previous ref seq
+          if (sequenceBuffer !== '') {
+            if (!refSeqDoc) {
+              throw new Error('No refSeq document found')
+            }
+            refSeqLen += sequenceBuffer.length
+            logger.debug?.(
+              `Creating refSeq chunk number ${chunkIndex} of "${refSeqDoc._id}"`,
+            )
+            // We cannot use Mongo 'session' / transaction here because Mongo has 16 MB limit for transaction
+            await refSeqChunkModel.create([
+              {
+                refSeq: refSeqDoc._id,
+                n: chunkIndex,
+                sequence: sequenceBuffer,
+                user,
+                status: -1,
+              },
+            ])
+            sequenceBuffer = ''
+          }
+          await refSeqDoc?.updateOne({ length: refSeqLen })
+          // await refSeqDoc?.updateOne({ length: refSeqLen }, { session })
+          refSeqLen = 0
+          chunkIndex = 0
+
+          const name = refSeqInfoLine[1].trim()
+          const description = refSeqInfoLine[2] ? refSeqInfoLine[2].trim() : ''
+
+          // We cannot use Mongo 'session' / transaction here because Mongo has 16 MB limit for transaction
+          const [newRefSeqDoc] = await refSeqModel.create([
+            {
+              name,
+              description,
+              assembly,
+              length: 0,
+              ...(customChunkSize ? { chunkSize: customChunkSize } : null),
+              user,
+              status: -1,
+            },
+          ])
+          logger.debug?.(
+            `Added new refSeq "${name}", desc "${description}", docId "${newRefSeqDoc._id}"`,
+          )
+          refSeqDoc = newRefSeqDoc
+        } else if (/\S/.test(line)) {
+          if (!refSeqDoc) {
+            throw new Error('No refSeq document found')
+          }
+          const { _id, chunkSize } = refSeqDoc
+          sequenceBuffer += line.replaceAll(/\s/g, '')
+          // If sequence block > chunk size then save chunk into Mongo
+          while (sequenceBuffer.length >= chunkSize) {
+            const sequence = sequenceBuffer.slice(0, chunkSize)
+            refSeqLen += sequence.length
+            logger.debug?.(
+              `Creating refSeq chunk number ${chunkIndex} of "${_id}"`,
+            )
+            // We cannot use Mongo 'session' / transaction here because Mongo has 16 MB limit for transaction
+            await refSeqChunkModel.create([
+              { refSeq: _id, n: chunkIndex, sequence, user, status: -1 },
+            ])
+            chunkIndex++
+            // Set remaining sequence
+            sequenceBuffer = sequenceBuffer.slice(chunkSize)
+            logger.debug?.(`Remaining sequence: "${sequenceBuffer}"`)
+          }
+        }
+      }
+    }
+    if (!parsingStarted) {
+      throw new Error('No reference sequences found in file')
+    }
+
+    if (sequenceBuffer || lastLineIsIncomplete) {
+      if (!refSeqDoc) {
+        throw new Error('No refSeq document found')
+      }
+      // If the file did not end with line break so the last line is incomplete
+      if (lastLineIsIncomplete) {
+        sequenceBuffer += incompleteLine
+      }
+      refSeqLen += sequenceBuffer.length
+      logger.verbose?.(
+        `*** Add the very last chunk to ref seq ("${refSeqDoc._id}", index ${chunkIndex} and total length for ref seq is ${refSeqLen}): "${sequenceBuffer}"`,
+      )
+      logger.debug?.(
+        `Creating refSeq chunk number ${chunkIndex} of "${refSeqDoc._id}"`,
+      )
+      // We cannot use Mongo 'session' / transaction here because Mongo has 16 MB limit for transaction
+      await refSeqChunkModel.create([
+        {
+          refSeq: refSeqDoc._id,
+          n: chunkIndex,
+          sequence: sequenceBuffer,
+          user,
+          status: -1,
+        },
+      ])
+      await refSeqDoc.updateOne({ length: refSeqLen })
+    }
+  }
+
+  private refSeqCache = new Map<string, RefSeqDocument>()
+
+  async removeExistingFeatures(backend: ServerDataStore) {
+    const { featureModel, refSeqModel } = backend
+    const { assembly, logger } = this
+    logger.debug?.(`Removing existing features for assembly = ${assembly}`)
+
+    const refSeqs: RefSeqDocument[] = await refSeqModel
+      .find({ assembly })
+      .exec()
+
+    for (const refSeq of refSeqs) {
+      await featureModel.deleteMany({ refSeq: refSeq._id })
+    }
+  }
+
+  async addFeatureIntoDb(gff3Feature: GFF3Feature, backend: ServerDataStore) {
+    const { featureModel, refSeqModel, user } = backend
+    const { assembly, logger, refSeqCache } = this
+
+    const [{ seq_id: refName }] = gff3Feature
+    if (!refName) {
+      throw new Error(
+        `Valid seq_id not found in feature ${JSON.stringify(gff3Feature)}`,
+      )
+    }
+    let refSeqDoc = refSeqCache.get(refName)
+    if (!refSeqDoc) {
+      refSeqDoc =
+        (await refSeqModel.findOne({ assembly, name: refName }).exec()) ??
+        undefined
+      if (refSeqDoc) {
+        refSeqCache.set(refName, refSeqDoc)
+      }
+    }
+    if (!refSeqDoc) {
+      throw new Error(
+        `RefSeq was not found by assembly "${assembly}" and seq_id "${refName}" not found`,
+      )
+    }
+    // Let's add featureId to parent feature
+    const featureIds: string[] = []
+
+    const newFeature = createFeature(gff3Feature, refSeqDoc._id, featureIds)
+    logger.debug?.(`So far feature ids are: ${featureIds.toString()}`)
+    // Add value to gffId
+    newFeature.attributes?._id
+      ? (newFeature.gffId = newFeature.attributes?._id.toString())
+      : (newFeature.gffId = newFeature._id)
+    logger.debug?.(
+      `********************* Assembly specific change create ${JSON.stringify(
+        newFeature,
+      )}`,
+    )
+
+    // Add into Mongo
+    // We cannot use Mongo 'session' / transaction here because Mongo has 16 MB limit for transaction
+    const [newFeatureDoc] = await featureModel.create([
+      { allIds: featureIds, ...newFeature, user, status: -1 },
+    ])
+    logger.verbose?.(`Added docId "${newFeatureDoc._id}"`)
+  }
+}
+
+function createFeature(
+  gff3Feature: GFF3Feature,
+  refSeq: string,
+  featureIds?: string[],
+): AnnotationFeatureSnapshot {
+  const [firstFeature] = gff3Feature
+  const {
+    attributes,
+    child_features: childFeatures,
+    end,
+    phase,
+    score,
+    seq_id: refName,
+    source,
+    start,
+    strand,
+    type,
+  } = firstFeature
+  if (!refName) {
+    throw new Error(
+      `feature does not have seq_id: ${JSON.stringify(firstFeature)}`,
+    )
+  }
+  if (!type) {
+    throw new Error(
+      `feature does not have type: ${JSON.stringify(firstFeature)}`,
+    )
+  }
+  if (start === null) {
+    throw new Error(
+      `feature does not have start: ${JSON.stringify(firstFeature)}`,
+    )
+  }
+  if (end === null) {
+    throw new Error(
+      `feature does not have end: ${JSON.stringify(firstFeature)}`,
+    )
+  }
+  const feature: AnnotationFeatureSnapshot = {
+    _id: new ObjectID().toHexString(),
+    gffId: '',
+    refSeq,
+    type,
+    start: start - 1,
+    end,
+  }
+  if (gff3Feature.length > 1) {
+    const lastEnd = Math.max(
+      ...gff3Feature.map((f) => {
+        if (f.end === null) {
+          throw new Error(`feature does not have end: ${JSON.stringify(f)}`)
+        }
+        return f.end
+      }),
+    )
+    feature.end = lastEnd
+    feature.discontinuousLocations = gff3Feature.map((f) => {
+      const { end: subEnd, phase: locationPhase, start: subStart } = f
+      if (subStart === null || subEnd === null) {
+        throw new Error(
+          `feature does not have start and/or end: ${JSON.stringify(f)}`,
+        )
+      }
+      let parsedPhase: 0 | 1 | 2 | undefined
+      if (locationPhase) {
+        switch (locationPhase) {
+          case '0': {
+            parsedPhase = 0
+
+            break
+          }
+          case '1': {
+            parsedPhase = 1
+
+            break
+          }
+          case '2': {
+            parsedPhase = 2
+
+            break
+          }
+          default: {
+            throw new Error(`Unknown phase: "${locationPhase}"`)
+          }
+        }
+      }
+      return { start: subStart - 1, end: subEnd, phase: parsedPhase }
+    })
+  }
+  if (strand) {
+    if (strand === '+') {
+      feature.strand = 1
+    } else if (strand === '-') {
+      feature.strand = -1
+    } else {
+      throw new Error(`Unknown strand: "${strand}"`)
+    }
+  }
+  if (score !== null) {
+    feature.score = score
+  }
+  if (phase) {
+    switch (phase) {
+      case '0': {
+        feature.phase = 0
+
+        break
+      }
+      case '1': {
+        feature.phase = 1
+
+        break
+      }
+      case '2': {
+        feature.phase = 2
+
+        break
+      }
+      default: {
+        throw new Error(`Unknown phase: "${phase}"`)
+      }
+    }
+  }
+  if (featureIds) {
+    featureIds.push(feature._id)
+  }
+
+  if (childFeatures?.length) {
+    const children: Record<string, AnnotationFeatureSnapshot> = {}
+    for (const childFeature of childFeatures) {
+      const child = createFeature(childFeature, refSeq, featureIds)
+      children[child._id] = child
+      // Add value to gffId
+      child.attributes?._id
+        ? (child.gffId = child.attributes?._id.toString())
+        : (child.gffId = child._id)
+    }
+    feature.children = children
+  }
+  if (source ?? attributes) {
+    const attrs: Record<string, string[]> = {}
+    if (source) {
+      attrs.source = [source]
+    }
+    if (attributes) {
+      for (const [key, val] of Object.entries(attributes)) {
+        if (val) {
+          const newKey = key.toLowerCase()
+          if (newKey !== 'parent') {
+            // attrs[key.toLowerCase()] = val
+            switch (key) {
+              case 'ID': {
+                attrs._id = val
+                break
+              }
+              case 'Name': {
+                attrs.gff_name = val
+                break
+              }
+              case 'Alias': {
+                attrs.gff_alias = val
+                break
+              }
+              case 'Target': {
+                attrs.gff_target = val
+                break
+              }
+              case 'Gap': {
+                attrs.gff_gap = val
+                break
+              }
+              case 'Derives_from': {
+                attrs.gff_derives_from = val
+                break
+              }
+              case 'Note': {
+                attrs.gff_note = val
+                break
+              }
+              case 'Dbxref': {
+                attrs.gff_dbxref = val
+                break
+              }
+              case 'Ontology_term': {
+                const goTerms: string[] = []
+                const otherTerms: string[] = []
+                for (const v of val) {
+                  if (v.startsWith('GO:')) {
+                    goTerms.push(v)
+                  } else {
+                    otherTerms.push(v)
+                  }
+                }
+                if (goTerms.length > 0) {
+                  attrs['Gene Ontology'] = goTerms
+                }
+                if (otherTerms.length > 0) {
+                  attrs.gff_ontology_term = otherTerms
+                }
+                break
+              }
+              case 'Is_circular': {
+                attrs.gff_is_circular = val
+                break
+              }
+              default: {
+                attrs[key.toLowerCase()] = val
+              }
+            }
+          }
+        }
+      }
+    }
+    feature.attributes = attrs
+  }
+  return feature
+}

package/src/Change.ts

@@ -0,0 +1,80 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-condition */
+/* eslint-disable @typescript-eslint/restrict-template-expressions */
+import {
+  AnnotationFeatureI,
+  AnnotationFeatureSnapshot,
+  ApolloAssemblyI,
+  CheckResultI,
+  CheckResultSnapshot,
+} from '@apollo-annotation/mst'
+import { AppRootModel, Region } from '@jbrowse/core/util'
+
+import { changeRegistry } from './ChangeTypeRegistry'
+import {
+  BackendDataStore,
+  Operation,
+  OperationOptions,
+  SerializedOperation,
+} from './Operation'
+
+export interface ClientDataStore {
+  typeName: 'Client'
+  assemblies: Map<string, ApolloAssemblyI>
+  checkResults: Map<string, CheckResultI>
+  internetAccounts: AppRootModel['internetAccounts']
+  getInternetAccount(
+    assemblyName?: string,
+    internetAccountId?: string,
+  ): AppRootModel['internetAccounts'][0]
+  loadFeatures(regions: Region[]): void
+  loadRefSeq(regions: Region[]): void
+  getFeature(featureId: string): AnnotationFeatureI | undefined
+  addFeature(assemblyId: string, feature: AnnotationFeatureSnapshot): void
+  deleteFeature(featureId: string): void
+  deleteAssembly(assemblyId: string): void
+  addCheckResults(checkResults: CheckResultSnapshot[]): void
+  addAssembly(assemblyId: string): ApolloAssemblyI
+}
+
+export type SerializedChange = SerializedOperation
+export type ChangeOptions = OperationOptions
+
+export type DataStore = BackendDataStore | ClientDataStore
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isChange(thing: any): thing is Change {
+  return (thing as Change).executeOnClient !== undefined
+}
+
+export abstract class Change extends Operation {
+  /**
+   * If a non-empty string, a snackbar will display in JBrowse with this message
+   * when a successful response is received from the server.
+   */
+  // eslint-disable-next-line @typescript-eslint/class-literal-property-style
+  get notification(): string {
+    return ''
+  }
+
+  static fromJSON(json: SerializedOperation, options?: ChangeOptions): Change {
+    const ChangeType = changeRegistry.getChangeType(json.typeName)
+    return new ChangeType(json, options?.logger && { logger: options.logger })
+  }
+
+  async execute(backend: DataStore): Promise<unknown> {
+    const backendType = backend.typeName
+    if (backendType === 'LocalGFF3' || backendType === 'Server') {
+      return super.execute(backend)
+    }
+    if (backendType === 'Client') {
+      return this.executeOnClient(backend)
+    }
+    throw new Error(
+      `no change implementation for backend type '${backendType}'`,
+    )
+  }
+
+  abstract executeOnClient(backend: ClientDataStore): Promise<void>
+
+  abstract getInverse(): Change
+}

package/src/ChangeTypeRegistry.ts

@@ -0,0 +1,26 @@
+import { Change } from './Change'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ChangeType = new (...args: any[]) => Change
+
+class ChangeTypeRegistry {
+  changes = new Map<string, ChangeType>()
+
+  registerChange(name: string, changeType: ChangeType): void {
+    if (this.changes.has(name)) {
+      throw new Error(`change type "${name}" has already been registered`)
+    }
+    this.changes.set(name, changeType)
+  }
+
+  getChangeType(name: string): ChangeType {
+    const RegisteredChangeType = this.changes.get(name)
+    if (!RegisteredChangeType) {
+      throw new Error(`No change constructor registered for "${name}"`)
+    }
+    return RegisteredChangeType
+  }
+}
+
+/** global singleton of all known types of changes */
+export const changeRegistry = new ChangeTypeRegistry()

package/src/Check.ts

@@ -0,0 +1,14 @@
+import {
+  AnnotationFeatureSnapshot,
+  CheckResultSnapshot,
+} from '@apollo-annotation/mst'
+
+export abstract class Check {
+  abstract name: string
+  abstract version: number
+
+  abstract checkFeature(
+    feature: AnnotationFeatureSnapshot,
+    getSequence: (start: number, end: number) => Promise<string>,
+  ): Promise<CheckResultSnapshot[]>
+}

package/src/CheckRegistry.ts

@@ -0,0 +1,27 @@
+import { Check } from './Check'
+
+class CheckRegistry {
+  checks = new Map<string, Check>()
+
+  registerCheck(name: string, check: Check): void {
+    if (this.checks.has(name)) {
+      throw new Error(`check "${name}" has already been registered`)
+    }
+    this.checks.set(name, check)
+  }
+
+  getCheck(name: string): Check {
+    const registeredCheck = this.checks.get(name)
+    if (!registeredCheck) {
+      throw new Error(`No check constructor registered for "${name}"`)
+    }
+    return registeredCheck
+  }
+
+  getChecks() {
+    return this.checks
+  }
+}
+
+/** global singleton of all known checks */
+export const checkRegistry = new CheckRegistry()

package/src/FeatureChange.ts

@@ -0,0 +1,118 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-condition */
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+import type { AnnotationFeatureSnapshot } from '@apollo-annotation/mst'
+import { Feature } from '@apollo-annotation/schemas'
+import ObjectID from 'bson-objectid'
+import type { Types } from 'mongoose'
+
+import {
+  AssemblySpecificChange,
+  SerializedAssemblySpecificChange,
+  isAssemblySpecificChange,
+} from './AssemblySpecificChange'
+import { ChangeOptions } from './Change'
+
+export interface SerializedFeatureChange
+  extends SerializedAssemblySpecificChange {
+  /** The IDs of features that were changed in this operation */
+  changedIds: string[]
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isFeatureChange(thing: any): thing is FeatureChange {
+  return (
+    isAssemblySpecificChange(thing) &&
+    (thing as FeatureChange).changedIds !== undefined
+  )
+}
+
+export abstract class FeatureChange extends AssemblySpecificChange {
+  changedIds: string[]
+
+  constructor(json: SerializedFeatureChange, options?: ChangeOptions) {
+    super(json, options)
+    this.changedIds = json.changedIds
+  }
+
+  /**
+   * Get single feature by featureId
+   * @param feature -
+   * @param featureId -
+   * @returns
+   */
+  getFeatureFromId(feature: Feature, featureId: string): Feature | null {
+    const { logger } = this
+    logger.verbose?.(`Entry=${JSON.stringify(feature)}`)
+
+    if (feature._id.equals(featureId)) {
+      logger.debug?.(
+        `Top level featureId matches in the object ${JSON.stringify(feature)}`,
+      )
+      return feature
+    }
+    // Check if there is also childFeatures in parent feature and it's not empty
+    // Let's get featureId from recursive method
+    logger.debug?.(
+      'FeatureId was not found on top level so lets make recursive call...',
+    )
+    for (const [, childFeature] of feature.children ?? new Map()) {
+      const subFeature = this.getFeatureFromId(childFeature, featureId)
+      if (subFeature) {
+        return subFeature
+      }
+    }
+    return null
+  }
+
+  /**
+   * Get children's feature ids
+   * @param feature - parent feature
+   * @returns
+   */
+  getChildFeatureIds(feature: Feature | AnnotationFeatureSnapshot): string[] {
+    if (!feature.children) {
+      return []
+    }
+    const featureIds = []
+    const children =
+      feature.children instanceof Map
+        ? feature.children
+        : new Map(Object.entries(feature.children))
+    for (const [childFeatureId, childFeature] of children || new Map()) {
+      featureIds.push(childFeatureId, ...this.getChildFeatureIds(childFeature))
+    }
+    return featureIds
+  }
+
+  /**
+   * Recursively assign new IDs to a feature
+   * @param feature - Parent feature
+   * @param featureIds -
+   */
+  generateNewIds(
+    feature: Feature | AnnotationFeatureSnapshot,
+    featureIds: string[],
+  ): AnnotationFeatureSnapshot {
+    const newId = new ObjectID().toHexString()
+    featureIds.push(newId)
+
+    const children: Record<string, AnnotationFeatureSnapshot> = {}
+    if (feature.children) {
+      for (const child of Object.values(feature.children)) {
+        const newChild = this.generateNewIds(child, featureIds)
+        children[newChild._id] = newChild
+      }
+    }
+    const refSeq =
+      typeof feature.refSeq === 'string'
+        ? feature.refSeq
+        : (feature.refSeq as unknown as Types.ObjectId).toHexString()
+
+    return {
+      ...feature,
+      refSeq,
+      children: feature.children && children,
+      _id: newId,
+    }
+  }
+}

package/src/Operation.ts

@@ -0,0 +1,98 @@
+/* eslint-disable @typescript-eslint/no-confusing-void-expression */
+/* eslint-disable @typescript-eslint/no-unnecessary-condition */
+/* eslint-disable @typescript-eslint/restrict-template-expressions */
+import type { ReadStream } from 'node:fs'
+import type { FileHandle } from 'node:fs/promises'
+
+import {
+  AssemblyDocument,
+  FeatureDocument,
+  FileDocument,
+  RefSeqChunkDocument,
+  RefSeqDocument,
+  UserDocument,
+} from '@apollo-annotation/schemas'
+import type { LoggerService } from '@nestjs/common'
+import type { ClientSession, Model } from 'mongoose'
+
+export interface LocalGFF3DataStore {
+  typeName: 'LocalGFF3'
+  gff3Handle: FileHandle
+}
+
+interface CreateFileDto {
+  readonly _id: string
+  readonly basename: string
+  readonly checksum: string
+  readonly type: 'text/x-gff3' | 'text/x-fasta'
+  readonly user: string
+}
+
+export interface ServerDataStore {
+  typeName: 'Server'
+  featureModel: Model<FeatureDocument>
+  assemblyModel: Model<AssemblyDocument>
+  refSeqModel: Model<RefSeqDocument>
+  refSeqChunkModel: Model<RefSeqChunkDocument>
+  fileModel: Model<FileDocument>
+  userModel: Model<UserDocument>
+  session: ClientSession
+  filesService: {
+    getFileStream(file: FileDocument): ReadStream
+    parseGFF3(stream: ReadStream): ReadStream
+    create(createFileDto: CreateFileDto): void
+    remove(id: string): void
+  }
+  pluginsService: {
+    evaluateExtensionPoint(
+      extensionPointName: string,
+      extendee: unknown,
+      props?: Record<string, unknown>,
+    ): void
+  }
+  counterService: {
+    getNextSequenceValue(sequenceName: string): Promise<number>
+  }
+  user: string
+}
+export interface SerializedOperation {
+  typeName: string
+}
+
+export type BackendDataStore = ServerDataStore | LocalGFF3DataStore
+
+export interface OperationOptions {
+  logger: LoggerService
+}
+
+export abstract class Operation implements SerializedOperation {
+  protected logger: LoggerService
+  abstract typeName: string
+
+  constructor(json: SerializedOperation, options?: OperationOptions) {
+    this.logger = options?.logger ?? console
+  }
+
+  abstract toJSON(): SerializedOperation
+
+  async execute(backend: BackendDataStore): Promise<unknown> {
+    const backendType = backend.typeName
+    if (backendType === 'Server') {
+      const initialResult = this.executeOnServer(backend)
+      return backend.pluginsService.evaluateExtensionPoint(
+        `${this.typeName}-transformResults`,
+        initialResult,
+        { operation: this, backend },
+      )
+    }
+    if (backendType === 'LocalGFF3') {
+      return this.executeOnLocalGFF3(backend)
+    }
+    throw new Error(
+      `no operation implementation for backend type '${backendType}'`,
+    )
+  }
+
+  abstract executeOnServer(backend: ServerDataStore): Promise<unknown>
+  abstract executeOnLocalGFF3(backend: LocalGFF3DataStore): Promise<unknown>
+}

package/src/OperationTypeRegistry.ts

@@ -0,0 +1,26 @@
+import { Operation } from './Operation'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type OperationType = new (...args: any[]) => Operation
+
+class OperationTypeRegistry {
+  operations = new Map<string, OperationType>()
+
+  registerOperation(name: string, operationType: OperationType): void {
+    if (this.operations.has(name)) {
+      throw new Error(`operation type "${name}" has already been registered`)
+    }
+    this.operations.set(name, operationType)
+  }
+
+  getOperationType(name: string): OperationType {
+    const RegisteredOperationType = this.operations.get(name)
+    if (!RegisteredOperationType) {
+      throw new Error(`No operation constructor registered for "${name}"`)
+    }
+    return RegisteredOperationType
+  }
+}
+
+/** global singleton of all known types of operations */
+export const operationRegistry = new OperationTypeRegistry()

package/src/Validation.ts

@@ -0,0 +1,52 @@
+/* eslint-disable @typescript-eslint/require-await */
+import { FeatureDocument } from '@apollo-annotation/schemas'
+import type { ExecutionContext } from '@nestjs/common'
+import type { Reflector } from '@nestjs/core'
+import { ClientSession, Model } from 'mongoose'
+
+import { Change, ClientDataStore } from './Change'
+
+export interface Context {
+  context: ExecutionContext
+  reflector: Reflector
+}
+
+export function isContext(thing: Change | Context): thing is Context {
+  return 'context' in thing && 'reflector' in thing
+}
+
+export interface ValidationResult {
+  validationName: string
+  error?: { message: string }
+}
+
+export abstract class Validation {
+  abstract name: string
+  async frontendPreValidate(_change: Change): Promise<ValidationResult> {
+    return { validationName: this.name }
+  }
+
+  async frontendPostValidate(
+    _change: Change,
+    _dataStore: ClientDataStore,
+  ): Promise<ValidationResult> {
+    return { validationName: this.name }
+  }
+
+  async backendPreValidate(
+    _changeOrContext: Change | Context,
+  ): Promise<ValidationResult> {
+    return { validationName: this.name }
+  }
+
+  async backendPostValidate(
+    _change: Change,
+    _context: { session: ClientSession; featureModel: Model<FeatureDocument> },
+  ): Promise<ValidationResult> {
+    return { validationName: this.name }
+  }
+
+  async possibleValues(_key: string): Promise<unknown[] | undefined> {
+    return undefined
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './ApolloPlugin'
+export * from './AssemblySpecificChange'
+export * from './Change'
+export * from './ChangeTypeRegistry'
+export * from './Check'
+export * from './CheckRegistry'
+export * from './FeatureChange'
+export * from './Operation'
+export * from './OperationTypeRegistry'
+export * from './Validation'

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "incremental": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "target": "ES2019",
+    "lib": ["ES2019", "DOM"],
+    "module": "CommonJS",
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strictPropertyInitialization": false,
+  },
+  "include": ["./src"],
+  "references": [
+    { "path": "../apollo-schemas"},
+  ]
+}