@zakodium/nmr-types 0.5.23 → 0.5.25

package/dist/nmr-types.d.ts

@@ -5,10 +5,14 @@ import type { GaussianShape1D } from 'ml-peak-shape-generator';
 import type { GeneralizedLorentzianShape1D } from 'ml-peak-shape-generator';
 import type { Logger } from 'cheminfo-types';
 import type { LorentzianShape1D } from 'ml-peak-shape-generator';
+import type { NmrData1D } from 'cheminfo-types';
+import type { NmrData2D } from 'cheminfo-types';
 import type { NumberArray } from 'cheminfo-types';
 import type { PeakXYWidth } from 'cheminfo-types';
 import type { PseudoVoigtShape1D } from 'ml-peak-shape-generator';
 import type { XYEquallySpacedOptions } from 'ml-spectra-processing';
+import type { z } from 'zod';
+import type { ZodType } from 'zod';
 
 export declare interface AirplsOptions {
     algorithm: 'airpls';
@@ -124,6 +128,13 @@ export declare interface BasePeak {
     id: string;
 }
 
+export declare interface BaseSpectrum {
+    id: string;
+    selector?: NmrLoaderSelectors;
+    meta: Metadata;
+    customInfo: any;
+}
+
 export declare interface BernsteinOptions {
     degree: number;
     algorithm: 'bernstein';
@@ -172,6 +183,11 @@ declare interface BooleanField extends Field<boolean> {
     type: 'boolean';
 }
 
+export declare interface Color2D {
+    positiveColor: string;
+    negativeColor: string;
+}
+
 declare type CommonField = SelectField | StringField | NumberField | BooleanField | LabelField;
 
 export declare interface CubicOptions {
@@ -218,6 +234,8 @@ export declare interface CubicOptions {
     medianWindow?: number;
 }
 
+export declare type DataSelectionOption = 'ft' | 'fid' | 'both' | 'preferFT' | 'preferFID';
+
 export declare interface DigitalFilter2DOptions extends BaseFilter {
     name: 'digitalFilter2D';
     value: DigitalFilterOptions_2;
@@ -243,6 +261,27 @@ export declare interface DirectDimensionOptions {
     phaseCorrection?: PhaseCorrection;
 }
 
+export declare interface Display {
+    isVisible: boolean;
+}
+
+export declare interface Display1D extends Display {
+    color: string;
+    isPeaksMarkersVisible: boolean;
+    isRealSpectrumVisible: boolean;
+    isVisibleInDomain: boolean;
+}
+
+export declare interface Display2D extends Color2D, Display {
+    isPositiveVisible: boolean;
+    isNegativeVisible: boolean;
+}
+
+export declare interface DomainUpdateRules {
+    readonly updateYDomain: boolean;
+    readonly updateXDomain: boolean;
+}
+
 declare type EquallySpacedFilterOptions = Pick<XYEquallySpacedOptions, 'from' | 'to' | 'numberOfPoints' | 'exclusions'>;
 
 export declare interface EquallySpacedOptions extends BaseFilter {
@@ -350,6 +389,29 @@ export declare interface GaussianOptions {
     lineBroadeningCenter: number;
 }
 
+export declare interface GeneralLoadersSelector {
+    /**
+     * priories processed or raw data if both exists
+     * @default 'both'
+     */
+    dataSelection?: DataSelectionOption;
+    /**
+     * should we ignore 1D spectra
+     * @default true
+     */
+    keep1D?: boolean;
+    /**
+     * should we ignore 2D spectra
+     * @default true
+     */
+    keep2D?: boolean;
+    /**
+     * should we keep only real part. we will ignore keepFID
+     * @default true
+     */
+    onlyReal?: boolean;
+}
+
 export declare interface IndirectDimensionOptions {
     acquisitionScheme?: string;
     reverse?: boolean;
@@ -500,6 +562,21 @@ export declare interface MatrixOptions<MatrixFilterOptions extends object> {
 
 export declare type MatrixProperties = Record<string, Properties>;
 
+export declare type Metadata = Record<string, any>;
+
+/**
+ * Plugins should use Declaration Merging on this interface.
+ * `NmrLoaderSelectors` is a selector used by NMRium loaders to filter the data to load
+ */
+export declare interface NmrLoaderSelectors {
+    /**
+     * Read methods take a file-collection input, the root is used to call `fileCollection.subroot(selector.root)`.
+     */
+    root?: string;
+    general?: GeneralLoadersSelector;
+    files?: string[];
+}
+
 export declare interface NMRPeak1D extends PeakXYWidth {
     id?: string;
     kind?: SignalKind;
@@ -627,6 +704,14 @@ export declare interface PolynomialOptions {
     degree: number;
 }
 
+/**
+ * Computed from Spectrum1DProcessingTypeRegistry and Spectrum2DProcessingTypeRegistry keys.
+ * Ensures type-safety on operator-registration.
+ *
+ * If the operator is not registered in the type registries. It should not be registerable in the operator registry.
+ */
+export declare type ProcessingOperatorId = Exclude<keyof SpectrumProcessingTypeRegistry, number>;
+
 declare type Properties = ListField | SelectField | StringField | NumberField | BooleanField | LabelField;
 
 export declare interface Range extends Omit<NMRRange, 'signals' | 'id'> {
@@ -737,6 +822,194 @@ export declare interface SineBellOptions {
 
 export declare type SineSquareOptions = Omit<SineBellOptions, 'exponent'>;
 
+export declare type Spectra = Spectrum[];
+
+export declare type Spectrum = Spectrum1D | Spectrum2D;
+
+export declare interface Spectrum1D extends BaseSpectrum {
+    /**
+     * Contains processed data.
+     *
+     * originalData -> processing pipeline -> data
+     */
+    data: NmrData1D;
+    /**
+     * Original data extracted from the use data files like jcamp / bruker and so-on.
+     */
+    originalData: NmrData1D;
+    peaks: Peaks;
+    display: Display1D;
+    integrals: Integrals;
+    ranges: Ranges;
+    info: Info1D;
+    originalInfo: Info1D;
+    filters: Filter1DEntry[];
+    /**
+     * EXPERIMENTAL type declaration.
+     * Can change anytime without migration.
+     */
+    processings?: Array<Spectrum1DProcessingTypeRegistry[keyof Spectrum1DProcessingTypeRegistry]>;
+}
+
+/**
+ * Registry of all the 1d spectrum processing operations.
+ * Each plugin adding operator for 1d spectrum processing should register their types here with declaration merging.
+ *
+ * Use the operatorId as the key, and SpectrumProcessingOperation<Settings, Options> as value.
+ *
+ * Spectrum1D type definition uses `processings?: Array<Spectrum1DProcessingTypeRegistry[keyof Spectrum1DProcessingTypeRegistry]>;`
+ *
+ * @example
+ * ```ts
+ * declare module '@zakodium/nmr-types' {
+ *  interface Spectrum1DProcessingTypeRegistry {
+ *    'my-package#myOperator': SpectrumProcessingOperation<MyOperatorSettings, MyOperatorOptions>;
+ *  }
+ * }
+ * ```
+ */
+export declare interface Spectrum1DProcessingTypeRegistry extends Record<string & {}, // string only break auto complete
+SpectrumProcessingOperation<unknown, unknown>> {
+}
+
+export declare type Spectrum1DSource = Partial<Spectrum1D>;
+
+export declare interface Spectrum2D extends BaseSpectrum {
+    zones: Zones;
+    /**
+     * Contains processed data.
+     *
+     * originalData -> processing pipeline -> data
+     */
+    data: NmrData2D;
+    info: Info2D;
+    originalInfo: Info2D;
+    display: Display2D;
+    /**
+     * Original data extracted from the use data files like jcamp / bruker and so-on.
+     */
+    originalData: NmrData2D;
+    filters: Filter2DEntry[];
+    /**
+     * EXPERIMENTAL type declaration.
+     * Can change anytime without migration.
+     */
+    processings?: Array<Spectrum2DProcessingTypeRegistry[keyof Spectrum2DProcessingTypeRegistry]>;
+}
+
+/**
+ * Registry of all the 2d spectrum processing operations.
+ * Each plugin adding operator for 2d spectrum processing should register their types here with declaration merging.
+ *
+ * Use the operatorId as the key, and SpectrumProcessingOperation<Settings, Options> as value.
+ *
+ * Spectrum2D type definition uses `processings?: Array<Spectrum2DProcessingTypeRegistry[keyof Spectrum2DProcessingTypeRegistry]>;`
+ *
+ * @example
+ * ```ts
+ * declare module '@zakodium/nmr-types' {
+ *  interface Spectrum2DProcessingTypeRegistry {
+ *    'my-package#myOperator': SpectrumProcessingOperation<MyOperatorSettings, MyOperatorOptions>;
+ *  }
+ * }
+ * ```
+ */
+export declare interface Spectrum2DProcessingTypeRegistry extends Record<string & {}, // string only break auto complete
+SpectrumProcessingOperation<unknown, unknown>> {
+}
+
+export declare type Spectrum2DSource = Partial<Spectrum2D>;
+
+/**
+ * A ProcessingOperation is a step in the processing pipeline.
+ * A ProcessingOperation can have no options: `ProcessingOperation<undefined>`.
+ * ProcessingOperation are stored in NMRiumState spectra in the processing field.
+ */
+export declare interface SpectrumProcessingOperation<Settings, Options> {
+    /**
+     * Unique identifier of the operation in the pipeline.
+     * React frontend constraint.
+     */
+    uid: string;
+    /**
+     * `id` of the operator registered in the core processing registry.
+     */
+    operatorId: ProcessingOperatorId;
+    /**
+     * User Parameters for the operation.
+     */
+    settings: Settings;
+    /**
+     * Computed Parameters for the operation.
+     * Computed from settings and the spectrum.
+     *
+     * If `undefined`, options should be computed.
+     */
+    options: Options | undefined;
+    /**
+     * Whether the operation is enabled or not.
+     */
+    enabled: boolean;
+    /**
+     * Error produced by the operation.
+     */
+    error: undefined | string;
+}
+
+export declare interface SpectrumProcessingOperator<SchemaSettings extends ZodType | null, SchemaOptions extends ZodType | null> {
+    /**
+     * Unique identifier (across the core operators registry) for the operation.
+     * Developer-readable, camelCase, package name as prefix.
+     *
+     * @example `@zakodium/nmrium-private-plugins#baselineCorrection`
+     */
+    id: ProcessingOperatorId;
+    /**
+     * Ensure the settings are valid for the operation.
+     * `null` if the operation doesn't need settings.
+     */
+    schemaSettings: SchemaSettings;
+    /**
+     * Ensure the options are valid for the operation.
+     * `null` if the operation doesn't need options, it implies `apply` will always receive `null` as options.
+     */
+    schemaOptions: SchemaOptions;
+    /**
+     * Function that takes the spectrum in the state of the current pipeline step,
+     * the operation’s settings, and returns options to apply the operation.
+     */
+    computeOptions: (spectrum: Spectrum, settings: z.output<SchemaSettings>) => z.output<SchemaOptions>;
+    /**
+     * Returns whether the operation can be applied on given data.
+     *
+     * @param data
+     */
+    isApplicable: (spectrum: Spectrum) => boolean;
+    /**
+     * Function that applies the operation to the spectrum given the options.
+     */
+    apply: (spectrum: Spectrum, options: z.output<SchemaOptions>) => Spectrum;
+    /**
+     * Hints to the caller that the operation will modify the data domain (either x, y, or both),
+     * requiring to reset it in the UI.
+     */
+    domainUpdateRules: DomainUpdateRules;
+}
+
+export declare interface SpectrumProcessingOperatorTypeRegistry extends Record<string & {}, SpectrumProcessingOperator<ZodType | null, ZodType | null>> {
+}
+
+/**
+ * Registry of all spectrum processing operations.
+ * Use it as a getter from operator id.
+ *
+ * Dedicated Spectrum1DProcessingTypeRegistry and Spectrum2DProcessingTypeRegistry are needed to fulfill Spectrum1D and Spectrum2D type definition.
+ *
+ * Plugin developers should not use declaration merging on this interface.
+ */
+export declare interface SpectrumProcessingTypeRegistry extends Spectrum1DProcessingTypeRegistry, Spectrum2DProcessingTypeRegistry {
+}
+
 export declare type SpectrumSource = 'prediction' | 'database' | 'unknown';
 
 declare interface StringField extends Field<string> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakodium/nmr-types",
-  "version": "0.5.23",
+  "version": "0.5.25",
   "description": "Types related to NMR data processing.",
   "author": "Zakodium Sàrl",
   "license": "CC-BY-NC-SA-4.0",
@@ -24,19 +24,20 @@
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "cheminfo-types": "^1.15.0",
     "esbuild": "^0.28.2",
     "rimraf": "^6.1.3",
     "typescript": "~6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "dependencies": {
+    "cheminfo-types": "^1.15.0",
     "ml-peak-shape-generator": "^5.5.0",
     "ml-signal-processing": "^2.2.2",
-    "ml-spectra-processing": "^14.33.0"
+    "ml-spectra-processing": "^14.33.0",
+    "zod": "^4.4.3"
   },
   "volta": {
     "extends": "../../../package.json"
   },
-  "gitHead": "36bc3cc25e2173bc8dd9236faebc0b082b937c89"
+  "gitHead": "c52bfe2085c7690604fbcbe2e06ef6de0a66428d"
 }