industrial-model 0.11.3 → 0.12.0

package/dist/calculator/index.d.ts

@@ -0,0 +1,250 @@
+import { CogniteClient } from '@cognite/sdk';
+import { D as DataModelId, L as DataModelRetrieveOptions, P as DataModelRetrieveItem, V as ViewDefinition, S as InstancesQueryRequest, T as InstancesQueryResponse, W as InstancesSearchRequest, X as InstancesSearchResponse, Y as InstancesAggregateRequest, Z as InstancesAggregateResponse, _ as InstancesApplyRequest, $ as InstancesApplyResponse, a0 as CogniteDatapointRetrieveOptions, a1 as CogniteDatapointResultItem, a2 as CogniteDatapointLatestItem, a3 as CogniteDatapointInsertItem, a4 as CogniteDatapointDeleteItem, a5 as CogniteFileUploadInfo, a6 as CogniteFileUploadResult, a7 as CogniteFileDownloadUrl, N as NodeId, f as DatapointAggregate } from '../types-CFkHwXW6.js';
+
+interface CognitePort {
+    retrieveDataModels(ids: DataModelId[], options?: DataModelRetrieveOptions): Promise<{
+        items: DataModelRetrieveItem[];
+    }>;
+    retrieveViews(ids: Array<{
+        space: string;
+        externalId: string;
+        version: string;
+    }>): Promise<{
+        items: ViewDefinition[];
+    }>;
+    queryInstances(request: InstancesQueryRequest): Promise<InstancesQueryResponse>;
+    searchInstances(request: InstancesSearchRequest): Promise<InstancesSearchResponse>;
+    aggregateInstances(request: InstancesAggregateRequest): Promise<InstancesAggregateResponse>;
+    applyInstances(request: InstancesApplyRequest): Promise<InstancesApplyResponse>;
+    retrieveDatapoints(options: CogniteDatapointRetrieveOptions): Promise<{
+        items: CogniteDatapointResultItem[];
+    }>;
+    retrieveLatestDatapoints(items: CogniteDatapointLatestItem[], options?: {
+        ignoreUnknownIds?: boolean;
+    }): Promise<{
+        items: CogniteDatapointResultItem[];
+    }>;
+    insertDatapoints(items: CogniteDatapointInsertItem[]): Promise<void>;
+    deleteDatapoints(items: CogniteDatapointDeleteItem[]): Promise<void>;
+    uploadFile(fileInfo: CogniteFileUploadInfo, content?: unknown): Promise<CogniteFileUploadResult>;
+    getFileDownloadUrls(ids: Array<{
+        instanceId: {
+            space: string;
+            externalId: string;
+        };
+    }>): Promise<CogniteFileDownloadUrl[]>;
+}
+
+/** A single computed datapoint of a calculation result. */
+type DataPoint = {
+    timestamp: Date;
+    value: number;
+};
+/**
+ * A time series input to a calculation.
+ *
+ * When `aggregateType` is set the datapoints are fetched as aggregates and a
+ * `granularity` is required; otherwise raw datapoints are used.
+ */
+type CalculatorParameter = {
+    /** The time series instance to read datapoints from. */
+    timeSeries: NodeId;
+    /** Optional aggregate to apply; requires `granularity` when set. */
+    aggregateType?: DatapointAggregate;
+    /** Aggregate granularity (e.g. `"1h"`); required when `aggregateType` is set. */
+    granularity?: string;
+    /** The placeholder name used to reference this parameter in the formula. */
+    alias: string;
+};
+/** A formula plus the parameters its placeholders resolve to. */
+type CalculatorQuery = {
+    /** Formula referencing parameters by ``{alias}`` (see `evaluate`). */
+    formula: string;
+    parameters: CalculatorParameter[];
+};
+/** The datapoints produced by evaluating a `CalculatorQuery`. */
+type CalculationResult = {
+    query: CalculatorQuery;
+    datapoints: DataPoint[];
+};
+
+/**
+ * Evaluates formula-based calculations over Cognite time series datapoints.
+ *
+ * Each {@link CalculatorQuery} pairs a formula with the parameters its
+ * placeholders resolve to. The calculator fetches the required datapoints
+ * (de-duplicating shared time series), aligns them by position and evaluates
+ * the formula element-by-element.
+ */
+declare class Calculator {
+    private readonly retriever;
+    constructor(cognite: CogniteClient | CognitePort);
+    /** Evaluate a single query over the given time range. */
+    calculate(query: CalculatorQuery, start: Date, end: Date): Promise<CalculationResult>;
+    /**
+     * Evaluate several queries over the given time range, retrieving every
+     * parameter's datapoints in a single de-duplicated round trip.
+     */
+    calculateMultiples(queries: CalculatorQuery[], start: Date, end: Date): Promise<CalculationResult[]>;
+}
+
+/** Binary arithmetic operators supported by the formula grammar. */
+type BinaryOp = "add" | "sub" | "mul" | "div" | "pow" | "mod";
+/** Unary arithmetic operators supported by the formula grammar. */
+type UnaryOp = "pos" | "neg";
+/** Comparison operators supported by the formula grammar. */
+type CompareOp = "eq" | "ne" | "lt" | "le" | "gt" | "ge";
+/** Boolean operators supported by the formula grammar. */
+type BoolOpKind = "and" | "or";
+type NameNode = {
+    readonly kind: "name";
+    readonly id: string;
+};
+type ConstantNode = {
+    readonly kind: "constant";
+    readonly value: number;
+};
+type BinOpNode = {
+    readonly kind: "binop";
+    readonly op: BinaryOp;
+    readonly left: ExprNode;
+    readonly right: ExprNode;
+};
+type UnaryOpNode = {
+    readonly kind: "unaryop";
+    readonly op: UnaryOp;
+    readonly operand: ExprNode;
+};
+type CompareNode = {
+    readonly kind: "compare";
+    readonly left: ExprNode;
+    readonly ops: readonly CompareOp[];
+    readonly comparators: readonly ExprNode[];
+};
+type BoolOpNode = {
+    readonly kind: "boolop";
+    readonly op: BoolOpKind;
+    readonly values: readonly ExprNode[];
+};
+type IfExpNode = {
+    readonly kind: "ifexp";
+    readonly test: ExprNode;
+    readonly body: ExprNode;
+    readonly orelse: ExprNode;
+};
+/** Any node of a compiled formula expression tree. */
+type ExprNode = NameNode | ConstantNode | BinOpNode | UnaryOpNode | CompareNode | BoolOpNode | IfExpNode;
+
+/** A parsed, validated formula ready to be evaluated over parameter series. */
+type CompiledFormula = {
+    /** The whitespace-normalized formula text. */
+    readonly raw: string;
+    /** The formula text after placeholders were replaced with safe identifiers. */
+    readonly expression: string;
+    /** The validated expression tree. */
+    readonly tree: ExprNode;
+    /** Original parameter names in first-appearance order. */
+    readonly variables: readonly string[];
+    /** Mapping of original parameter name to its safe identifier. */
+    readonly nameMap: ReadonlyMap<string, string>;
+    /** Whether the formula needs element-by-element (short-circuiting) evaluation. */
+    readonly hasConditional: boolean;
+};
+/**
+ * Normalize the formula text, then compile it (memoized by normalized text).
+ *
+ * The public entry point mirrors the Python ``compile_formula`` helper: it
+ * exposes {@link clearCache} so callers can inspect or reset the compilation
+ * cache.
+ */
+declare function compileFormula(formula: string): CompiledFormula;
+/** Clear the memoized formula compilation cache. */
+declare function clearCache(): void;
+
+/** A single formula parameter: an aligned sequence of numeric values. */
+type ParameterValue = readonly number[];
+/** The result of evaluating a formula: one value per aligned series element. */
+type EvaluationResult = number[];
+/** Mapping of parameter name to its numeric series. */
+type Parameters = Record<string, ParameterValue>;
+
+/**
+ * Evaluate a formula over aligned numeric parameter sequences.
+ *
+ * Placeholders are written as ``{name}`` and each resolves to the matching
+ * entry in `parameters`. The following operators are supported:
+ *
+ * - arithmetic: ``+`` ``-`` ``*`` ``/`` ``**`` ``%`` (binary) and ``+`` ``-`` (unary)
+ * - comparisons: ``==`` ``!=`` ``<`` ``<=`` ``>`` ``>=``
+ * - boolean: ``and`` ``or``
+ * - conditional: ``{A} / {B} if {B} != 0 else 0``
+ *
+ * Structural problems (bad syntax, unknown identifiers, missing parameters,
+ * mismatched lengths, non-numeric values) throw a subclass of `FormulaError`.
+ *
+ * When every referenced parameter is an empty sequence the result is an empty
+ * array — there is nothing to compute over, so this is treated as a valid
+ * (empty) result rather than an error. A *mix* of empty and non-empty
+ * parameters is still a length mismatch and throws `ParameterLengthError`.
+ *
+ * Arithmetic failures that depend on the parameter *values* are surfaced as
+ * arithmetic errors (subclasses of `ArithmeticError`) rather than
+ * `FormulaError`: dividing or taking a modulo by zero throws
+ * `ZeroDivisionError` and an overflowing exponentiation throws `OverflowError`.
+ *
+ * Conditional expressions, comparisons and boolean operators are evaluated
+ * element-by-element: for each series element only the selected branch is
+ * evaluated, so a division-by-zero (or other value-dependent failure) in the
+ * branch that is *not* selected for a given element never throws.
+ */
+declare function evaluate(formula: string, parameters?: Parameters): EvaluationResult;
+
+/**
+ * Structural formula problems (bad syntax, unknown identifiers, missing
+ * parameters, mismatched lengths, non-numeric values) are reported as a
+ * subclass of {@link FormulaError}.
+ *
+ * Value-dependent arithmetic failures (division/modulo by zero, overflowing
+ * exponentiation) are intentionally *not* {@link FormulaError}s: they mirror
+ * the native errors raised by the Python implementation and extend
+ * {@link ArithmeticError} instead.
+ */
+/** Base error for every structural formula problem. */
+declare class FormulaError extends Error {
+    constructor(message: string);
+}
+/** Raised when formula syntax or operations are not supported. */
+declare class InvalidFormulaError extends FormulaError {
+    constructor(message: string);
+}
+/** Raised when a formula references parameters that were not provided. */
+declare class MissingParameterError extends FormulaError {
+    readonly missing: readonly string[];
+    constructor(missing: string[]);
+}
+/** Raised when a parameter value is not a valid numeric sequence. */
+declare class ParameterError extends FormulaError {
+    constructor(message: string);
+}
+/** Raised when referenced parameters do not all share the same length. */
+declare class ParameterLengthError extends ParameterError {
+    readonly lengths: Readonly<Record<string, number>>;
+    constructor(lengths: Record<string, number>);
+}
+/**
+ * Base for value-dependent arithmetic failures. Mirrors Python's built-in
+ * ``ArithmeticError`` and is deliberately separate from {@link FormulaError}.
+ */
+declare class ArithmeticError extends Error {
+    constructor(message: string);
+}
+/** Raised when a division or modulo has a zero divisor. */
+declare class ZeroDivisionError extends ArithmeticError {
+    constructor(message: string);
+}
+/** Raised when an exponentiation overflows the floating-point range. */
+declare class OverflowError extends ArithmeticError {
+    constructor(message: string);
+}
+
+export { ArithmeticError, type CalculationResult, Calculator, type CalculatorParameter, type CalculatorQuery, type CompiledFormula, type DataPoint, type EvaluationResult, FormulaError, InvalidFormulaError, MissingParameterError, OverflowError, ParameterError, ParameterLengthError, type ParameterValue, type Parameters, ZeroDivisionError, clearCache, compileFormula, evaluate };