@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tm1-client/services/element-service.d.ts

@@ -0,0 +1,245 @@
+import { TM1Error } from "../../types.js";
+import type { CellValue, ElementAttributeValue, ElementCreate, ElementUpdate } from "../../types.js";
+import type { TM1HttpClient } from "../http.js";
+import type { BatchService } from "./batch-service.js";
+import type { CellService } from "./cell-service.js";
+/** Read-only preview of {@link ElementService.bulkUpsert}. */
+export interface BulkUpsertPlan {
+    creates: string[];
+    updates: string[];
+    typeChanges: Array<{
+        name: string;
+        from: string;
+        to: string;
+    }>;
+    /** Existing children a components list would drop, per consolidation. */
+    removals: Array<{
+        parent: string;
+        children: string[];
+    }>;
+}
+/** Outcome of one element in {@link ElementService.deleteMany}. */
+export interface ElementDeleteResult {
+    elementName: string;
+    deleted: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export declare function isAlreadyExists(err: TM1Error): boolean;
+export declare class ElementService {
+    private readonly http;
+    private readonly cells;
+    private readonly batch?;
+    constructor(http: TM1HttpClient, cells: CellService, batch?: BatchService | undefined);
+    /**
+     * Create an element in a hierarchy. Consolidated elements may include
+     * Components inline; their target elements must already exist.
+     * POST /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements
+     */
+    /**
+     * Set edge weights that differ from TM1's default.
+     *
+     * TM1 accepts `Weight` inside a Components link payload and ignores it: the
+     * edge is created with weight 1 whatever the body said. Verified live — a
+     * consolidation created with weight -1 read back as 1 from the Edges
+     * collection itself, so no reader could have recovered the intent. The
+     * weight lives on the Edge entity and has to be PATCHed once the link
+     * exists.
+     *
+     * Only deviating weights cost a request: consolidations are overwhelmingly
+     * all-1, and a PATCH that sets 1 to 1 is a round trip for nothing.
+     */
+    private applyEdgeWeights;
+    /**
+     * Does an element resolve in a hierarchy the way TI would resolve it?
+     * The key lookup is TM1's own name resolution: case- and space-insensitive,
+     * and it accepts an alias (verified on 11.8.03500: 'northamerica' and the
+     * alias 'NA' both resolve 'North America'). 404 → false; anything else,
+     * including a denial, is rethrown — "you may not look" is not "missing".
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{e}')?$select=Name
+     */
+    exists(dimensionName: string, hierarchyName: string, elementName: string): Promise<boolean>;
+    create(dimensionName: string, hierarchyName: string, element: ElementCreate): Promise<void>;
+    /**
+     * Update an existing element (rename, type change, replace components).
+     * PATCH /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')
+     */
+    update(dimensionName: string, hierarchyName: string, elementName: string, update: ElementUpdate): Promise<void>;
+    /**
+     * Delete an element. May fail if the element is referenced in rules.
+     * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')
+     */
+    delete(dimensionName: string, hierarchyName: string, elementName: string): Promise<void>;
+    /**
+     * What a bulkUpsert of `elements` would do, read-only: which elements it
+     * creates, which it updates, which change type in place (a Numeric ->
+     * Consolidated/String conversion discards leaf data), and which existing
+     * children a `components` list would drop — components REPLACE the child
+     * set, they do not append.
+     *
+     * Computed BEFORE any write on purpose: bulkUpsert's $batch pass commits its
+     * creates as it goes (TM1's $batch is non-atomic), so a plan worked out
+     * afterwards could only report damage, not prevent it.
+     *
+     * One filtered read per 40 names — `Elements?$filter=Name eq … or …` with
+     * the edges expanded — instead of loading the hierarchy.
+     */
+    planBulkUpsert(dimensionName: string, hierarchyName: string, elements: ElementCreate[]): Promise<BulkUpsertPlan>;
+    /**
+     * Delete many elements of one hierarchy. Through `$batch` when the server
+     * has it (one DELETE sub-request per element, chunked by BatchService), else
+     * per request with bounded concurrency.
+     *
+     * Never all-or-nothing: TM1's `$batch` is non-atomic, so each element gets
+     * its own result and one missing name does not stop the rest. A systemic
+     * failure (auth, transport) still aborts the call.
+     *
+     * Falling back after BatchUnsupportedError is safe: that error is only raised
+     * before the first successful batch on the connection. Should a refused
+     * envelope still have removed some elements, their per-request replay
+     * reports NOT_FOUND instead of claiming a second delete.
+     */
+    deleteMany(dimensionName: string, hierarchyName: string, elementNames: string[]): Promise<ElementDeleteResult[]>;
+    /**
+     * Scan element names in a hierarchy with a hard cap, paginating server-side.
+     *
+     * A single bulk Elements fetch can exceed V8's max string length on large
+     * dimensions (response.text() buffers the whole body into one string), so
+     * this probes the total via $count on the first page, then pages by
+     * `pageSize` until either `maxScan` names are collected or the hierarchy is
+     * exhausted. Callers learn the true `total` and whether the scan was
+     * `truncated` — never a silent skip. Owns the V8-string-limit workaround so
+     * tools don't reimplement raw OData paging.
+     *
+     * `opts.filter` narrows the scan to names matching an OData predicate, and
+     * changes what the numbers mean: the server then evaluates every element and
+     * returns only the matches, so `scanned` becomes the hierarchy total (the
+     * server checked all of it) and `truncated` reports a capped MATCH set
+     * rather than a partial walk. That is the difference between an audit that
+     * examines the first 100k names and one that examines the dimension —
+     * see src/lib/naming/odata-filter.ts.
+     *
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements?$select=Name
+     */
+    scanElementNames(dimensionName: string, hierarchyName: string, opts: {
+        pageSize: number;
+        maxScan: number;
+        filter?: string;
+        /**
+         * Hierarchy size, when the caller already knows it. With a filter the
+         * response counts MATCHES, so the scope figure would otherwise cost an
+         * extra request per hierarchy — and the dimension listing can carry it
+         * for free via a nested $count.
+         */
+        scopeTotal?: number;
+    }): Promise<{
+        names: string[];
+        total: number;
+        scanned: number;
+        truncated: boolean;
+    }>;
+    /**
+     * Add an element as a component of a new parent.
+     * POST /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{newParent}')/Components
+     */
+    move(dimensionName: string, hierarchyName: string, elementName: string, newParent: string, weight?: number): Promise<void>;
+    /**
+     * Bulk upsert elements into a hierarchy. Two-pass to ensure leaves exist
+     * before consolidations reference them: pass 1 creates/upserts every element
+     * (PATCH on 409), pass 2 sets Components for Consolidated elements.
+     * POST/PATCH /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements(...)
+     *
+     * Prefers OData `$batch` (a handful of round-trips) and falls back to the
+     * per-request fan-out when the server has no `$batch` endpoint. Both paths
+     * produce the identical result and the identical throw-on-any-failure
+     * contract; only the number of HTTP calls differs.
+     */
+    bulkUpsert(dimensionName: string, hierarchyName: string, elements: ElementCreate[]): Promise<{
+        typeChanges: Array<{
+            name: string;
+            from: string;
+            to: string;
+        }>;
+    }>;
+    /**
+     * `$batch` implementation of bulkUpsert: four PASSES regardless of element
+     * count — create-all, read-type-of-the-ones-that-existed,
+     * patch-the-types-that-differ, then the consolidation Components patches.
+     * Each pass is chunked inside BatchService by request count AND serialized
+     * size, so N elements cost roughly 4 * ceil(N/200) calls instead of N —
+     * more when the sub-requests are large enough to hit the byte budget first.
+     */
+    private bulkUpsertViaBatch;
+    /**
+     * Per-request fallback for bulkUpsert, used when the server has no `$batch`.
+     * Fans the calls out with bounded concurrency.
+     */
+    private bulkUpsertPerRequest;
+    /**
+     * List element-attribute definitions for a hierarchy.
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/ElementAttributes
+     */
+    listAttributes(dimensionName: string, hierarchyName: string): Promise<Array<{
+        name: string;
+        type: "Numeric" | "String" | "Alias";
+    }>>;
+    /**
+     * Define a new element attribute on a hierarchy. Prefer TI prolog
+     * (DimensionElementInsert on `}ElementAttributes_{dim}`) for reproducible
+     * deployments — this REST path is for ad-hoc / debugging use.
+     * POST /api/v1/Dimensions('{d}')/Hierarchies('{h}')/ElementAttributes
+     */
+    createAttribute(dimensionName: string, hierarchyName: string, attributeName: string, attributeType: "Numeric" | "String" | "Alias"): Promise<void>;
+    /**
+     * Read all attribute values for one element via MDX on
+     * `}ElementAttributes_{Dim}`. Routes through CellService.executeMdx for the
+     * cellset round-trip.
+     */
+    getAttributeValues(dimensionName: string, elementName: string): Promise<ElementAttributeValue[]>;
+    /**
+     * Attribute values for a window of elements — every element of the
+     * dimension's default hierarchy, name-sorted, `limit` at a time. One MDX
+     * against `}ElementAttributes_{Dim}` with the window pushed into the row set
+     * (`SUBSET(TM1SORT(TM1SUBSETALL(...)))`), so the query text stays short no
+     * matter how many elements a page holds — TM1's request entity limit can be
+     * as low as 32 KB. `total` comes from `$count` on the Elements collection.
+     *
+     * `attributeNames` narrows the columns; omitted, every attribute is read.
+     */
+    getAttributeValuesPage(dimensionName: string, opts: {
+        offset: number;
+        limit: number;
+        attributeNames?: string[];
+    }): Promise<{
+        total: number;
+        items: Array<{
+            elementName: string;
+            values: Record<string, CellValue>;
+        }>;
+    }>;
+    /**
+     * Set a single attribute value. See {@link updateAttributeValues}.
+     */
+    updateAttributeValue(dimensionName: string, elementName: string, attributeName: string, value: number | string): Promise<void>;
+    /**
+     * Set attribute values by writing to the `}ElementAttributes_{Dim}` control
+     * cube — every update in ONE cellset write (CellService.writeCells).
+     *
+     * Values are coerced to the attribute's type, looked up once: a Numeric
+     * attribute takes a number or a numeric string (`"12.5"`), String and Alias
+     * attributes take the value as text. An unknown attribute or a non-numeric
+     * value for a Numeric attribute is a VALIDATION_ERROR that names it, raised
+     * before anything is written.
+     *
+     * Prefer TI processes (CellPutS / AttrPutS) for reproducible deployments;
+     * this REST-direct path is for ad-hoc / debugging use.
+     */
+    updateAttributeValues(dimensionName: string, updates: Array<{
+        elementName: string;
+        attributeName: string;
+        value: number | string;
+    }>): Promise<void>;
+}
+//# sourceMappingURL=element-service.d.ts.map