@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tm1-client/services/element-service.js

@@ -0,0 +1,809 @@
+// Element domain service. Owns the OData calls under
+// /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements(...) — create, update,
+// delete, move, bulk upsert, ElementAttribute definition CRUD, plus the
+// element-attribute VALUE read/write that goes through the
+// `}ElementAttributes_{Dim}` control cube. Those last two methods route
+// through CellService for the underlying MDX read and cellset PATCH.
+//
+// See docs/ARCHITECTURE.md for the layering.
+import { mapSettledWithConcurrency } from "../../lib/concurrency.js";
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+import { BatchUnsupportedError } from "./batch-service.js";
+import { rethrowIfSystemic } from "./fallback.js";
+// Max in-flight per-element REST calls within a single bulkUpsert pass. Bounds
+// pressure on TM1's worker pool (mirrors the cap the feeder-audit fan-out uses)
+// while removing the serialized 2-3N round-trips on an explicitly-bulk op.
+const BULK_UPSERT_CONCURRENCY = 8;
+// OData key encoder: double ' per OData literal rules, then percent-encode.
+const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+// TM1 signals "element already exists" with different HTTP statuses across
+// versions: some return 409 Conflict, but v11.x (REST 11.8) returns 400 with
+// the message "An element with name ... already exists". Detect both so bulk
+// upsert stays idempotent (update existing) rather than throwing on re-upsert.
+export function isAlreadyExists(err) {
+    if (err.httpStatus === 409)
+        return true;
+    if (err.httpStatus === 400) {
+        const text = `${err.message} ${err.details ?? ""}`.toLowerCase();
+        return text.includes("already exists");
+    }
+    return false;
+}
+// TM1 may report an element's Type as the enum name ("Numeric"|"String"|
+// "Consolidated") or its ordinal (1|2|3). Normalize to the name so callers can
+// compare against ElementCreate.type regardless of representation.
+function normalizeElementType(t) {
+    switch (t) {
+        case 1:
+        case "1":
+            return "Numeric";
+        case 2:
+        case "2":
+            return "String";
+        case 3:
+        case "3":
+            return "Consolidated";
+        default:
+            return String(t);
+    }
+}
+/**
+ * Reject with the first failure in ELEMENT order (not response order), so the
+ * error a caller sees is the same one the per-request path would surface.
+ * Successful sub-requests in the same batch stay committed — TM1's $batch is
+ * non-atomic — exactly as the concurrent per-request path already leaves
+ * earlier writes committed when a later one fails.
+ */
+function throwFirstFailure(results, indexOf) {
+    let firstIndex = Number.POSITIVE_INFINITY;
+    let firstError;
+    for (const r of results) {
+        if (r.ok)
+            continue;
+        const i = indexOf(r.id);
+        if (i < firstIndex) {
+            firstIndex = i;
+            firstError = r.error;
+        }
+    }
+    if (firstError)
+        throw firstError;
+}
+export class ElementService {
+    http;
+    cells;
+    batch;
+    constructor(http, cells, 
+    // Optional so a caller (and the existing unit tests) can build an
+    // ElementService that only ever uses the per-request path. Production wires
+    // it, which turns bulkUpsert's N round-trips into a handful of $batch calls.
+    batch) {
+        this.http = http;
+        this.cells = cells;
+        this.batch = batch;
+    }
+    /**
+     * 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.
+     */
+    async applyEdgeWeights(dimensionName, hierarchyName, parentName, components) {
+        const base = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')`;
+        for (const c of components) {
+            if (c.weight === undefined || c.weight === 1)
+                continue;
+            await this.http.request("PATCH", `${base}/Edges(ParentName='${enc(parentName)}',ComponentName='${enc(c.name)}')`, { Weight: c.weight });
+        }
+    }
+    /**
+     * 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
+     */
+    async exists(dimensionName, hierarchyName, elementName) {
+        try {
+            await this.http.request("GET", `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(elementName)}')?$select=Name`);
+            return true;
+        }
+        catch (e) {
+            if (e instanceof TM1Error && e.code === TM1ErrorCode.NOT_FOUND)
+                return false;
+            throw e;
+        }
+    }
+    async create(dimensionName, hierarchyName, element) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements`;
+        const body = {
+            Name: element.name,
+            Type: element.type,
+        };
+        if (element.type === "Consolidated" &&
+            element.components &&
+            element.components.length > 0) {
+            body.Components = element.components.map((c) => ({
+                "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(c.name)}')`,
+            }));
+        }
+        await this.http.request("POST", path, body);
+        if (element.components && element.components.length > 0) {
+            await this.applyEdgeWeights(dimensionName, hierarchyName, element.name, element.components);
+        }
+    }
+    /**
+     * Update an existing element (rename, type change, replace components).
+     * PATCH /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')
+     */
+    async update(dimensionName, hierarchyName, elementName, update) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(elementName)}')`;
+        const body = {};
+        if (update.newName !== undefined) {
+            body.Name = update.newName;
+        }
+        if (update.type !== undefined) {
+            body.Type = update.type;
+        }
+        if (update.components !== undefined) {
+            body.Components = update.components.map((c) => ({
+                "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(c.name)}')`,
+            }));
+        }
+        await this.http.request("PATCH", path, body);
+        if (update.components !== undefined) {
+            await this.applyEdgeWeights(dimensionName, hierarchyName, 
+            // A rename in the same PATCH takes effect immediately, so the edge
+            // key must use the NEW parent name.
+            update.newName ?? elementName, update.components);
+        }
+    }
+    /**
+     * Delete an element. May fail if the element is referenced in rules.
+     * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')
+     */
+    async delete(dimensionName, hierarchyName, elementName) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(elementName)}')`;
+        await this.http.request("DELETE", path);
+    }
+    /**
+     * 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.
+     */
+    async planBulkUpsert(dimensionName, hierarchyName, elements) {
+        const base = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements`;
+        const lit = (n) => `'${n.replace(/'/g, "''")}'`;
+        const current = new Map();
+        const names = [...new Set(elements.map((e) => e.name))];
+        for (let i = 0; i < names.length; i += 40) {
+            const chunk = names.slice(i, i + 40);
+            const filter = chunk.map((n) => `Name eq ${lit(n)}`).join(" or ");
+            const page = await this.http.request("GET", `${base}?$select=Name,Type&$expand=Edges($select=ComponentName)&$filter=${encodeURIComponent(filter)}`);
+            for (const e of page.value)
+                current.set(e.Name.toLowerCase(), {
+                    type: e.Type,
+                    children: (e.Edges ?? []).map((x) => x.ComponentName),
+                });
+        }
+        const plan = {
+            creates: [],
+            updates: [],
+            typeChanges: [],
+            removals: [],
+        };
+        for (const el of elements) {
+            const now = current.get(el.name.toLowerCase());
+            if (!now) {
+                plan.creates.push(el.name);
+                continue;
+            }
+            plan.updates.push(el.name);
+            if (now.type !== el.type)
+                plan.typeChanges.push({ name: el.name, from: now.type, to: el.type });
+            if (el.type === "Consolidated" &&
+                el.components &&
+                el.components.length > 0) {
+                const keep = new Set(el.components.map((c) => c.name.toLowerCase()));
+                const dropped = now.children.filter((c) => !keep.has(c.toLowerCase()));
+                if (dropped.length > 0)
+                    plan.removals.push({ parent: el.name, children: dropped });
+            }
+        }
+        return plan;
+    }
+    /**
+     * 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.
+     */
+    async deleteMany(dimensionName, hierarchyName, elementNames) {
+        const pathOf = (name) => `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(name)}')`;
+        const failed = (elementName, e) => ({
+            elementName,
+            deleted: false,
+            error: { code: e.code, message: e.message },
+        });
+        if (this.batch && !this.batch.isKnownUnsupported) {
+            try {
+                const results = await this.batch.execute(elementNames.map((name, i) => ({
+                    id: `d${i}`,
+                    method: "DELETE",
+                    path: pathOf(name),
+                })));
+                const byIndex = new Map(results.map((r) => [Number(r.id.slice(1)), r]));
+                return elementNames.map((elementName, i) => {
+                    const r = byIndex.get(i);
+                    if (r === undefined)
+                        return failed(elementName, new TM1Error({
+                            code: TM1ErrorCode.TM1_ERROR,
+                            message: "No sub-response for this element in the $batch reply.",
+                        }));
+                    return r.ok
+                        ? { elementName, deleted: true }
+                        : failed(elementName, r.error);
+                });
+            }
+            catch (err) {
+                if (!(err instanceof BatchUnsupportedError))
+                    throw err;
+            }
+        }
+        const settled = await mapSettledWithConcurrency(elementNames, BULK_UPSERT_CONCURRENCY, async (name) => {
+            await this.http.request("DELETE", pathOf(name));
+        });
+        return settled.map((r, i) => {
+            const elementName = elementNames[i];
+            if (r.status === "fulfilled")
+                return { elementName, deleted: true };
+            rethrowIfSystemic(r.reason);
+            return failed(elementName, r.reason);
+        });
+    }
+    /**
+     * 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
+     */
+    async scanElementNames(dimensionName, hierarchyName, opts) {
+        const { pageSize, maxScan, filter, scopeTotal } = opts;
+        const hierarchyPath = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')`;
+        const basePath = `${hierarchyPath}/Elements?$select=Name&$top=${pageSize}` +
+            (filter ? `&$filter=${encodeURIComponent(filter)}` : "");
+        // First page carries $count=true so we learn the total in one round-trip
+        // without the /$count endpoint (TM1 v11 returns text/plain there and
+        // rejects the Accept: application/json the shared HTTP client sends).
+        const firstPage = await this.http.request("GET", `${basePath}&$skip=0&$count=true`);
+        const total = firstPage["@odata.count"] ?? firstPage.value.length;
+        const scanLimit = Math.min(total, maxScan);
+        const names = [];
+        const firstSliceEnd = Math.min(firstPage.value.length, scanLimit);
+        for (let i = 0; i < firstSliceEnd; i++) {
+            names.push(firstPage.value[i].Name);
+        }
+        let skip = firstPage.value.length;
+        let lastPageSize = firstPage.value.length;
+        while (lastPageSize === pageSize && names.length < scanLimit) {
+            const page = await this.http.request("GET", `${basePath}&$skip=${skip}`);
+            const remaining = scanLimit - names.length;
+            const sliceEnd = Math.min(page.value.length, remaining);
+            for (let i = 0; i < sliceEnd; i++) {
+                names.push(page.value[i].Name);
+            }
+            lastPageSize = page.value.length;
+            skip += page.value.length;
+        }
+        if (filter === undefined) {
+            return {
+                names,
+                total,
+                scanned: names.length,
+                truncated: total > maxScan,
+            };
+        }
+        // With a filter, `total` above counted the MATCHES. The caller still wants
+        // to report how large the hierarchy was; when it already knows, that costs
+        // nothing, otherwise one 145-byte probe.
+        let inScope = scopeTotal;
+        if (inScope === undefined) {
+            const scopeProbe = await this.http.request("GET", `${hierarchyPath}/Elements?$select=Name&$top=0&$count=true`);
+            inScope = scopeProbe["@odata.count"] ?? total;
+        }
+        return {
+            names,
+            total: inScope,
+            scanned: inScope,
+            truncated: total > maxScan,
+        };
+    }
+    /**
+     * Add an element as a component of a new parent.
+     * POST /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{newParent}')/Components
+     */
+    async move(dimensionName, hierarchyName, elementName, newParent, weight) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(newParent)}')/Components`;
+        const body = {
+            "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(elementName)}')`,
+        };
+        await this.http.request("POST", path, body);
+        await this.applyEdgeWeights(dimensionName, hierarchyName, newParent, [
+            { name: elementName, ...(weight !== undefined ? { weight } : {}) },
+        ]);
+    }
+    /**
+     * 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.
+     */
+    async bulkUpsert(dimensionName, hierarchyName, elements) {
+        if (this.batch && !this.batch.isKnownUnsupported) {
+            try {
+                return await this.bulkUpsertViaBatch(dimensionName, hierarchyName, elements);
+            }
+            catch (err) {
+                // ONLY "this server has no $batch" falls through. A sub-request failure
+                // is not an exception here (it is reported per item and rethrown as the
+                // element error), and a systemic transport/auth error propagates from
+                // BatchService — neither may silently re-drive the writes.
+                //
+                // Restarting on the per-request path cannot duplicate or lose work —
+                // but NOT because nothing was committed. TM1's $batch is non-atomic
+                // (verified live), so an envelope that fails mid-way leaves the
+                // sub-requests it already processed in place. What makes the restart
+                // safe is WHICH sub-requests those can be: BatchService raises
+                // BatchUnsupportedError only before the first successful batch on the
+                // connection, and the only pass that can run before that is pass 1a —
+                // create-only. Re-creating an element the failed batch already created
+                // just takes the "already exists" upsert branch, sees the type it was
+                // created with, and patches nothing.
+                //
+                // The destructive passes are unreachable here by construction: pass 1c
+                // (Type PATCH) and pass 2 (Components) only run after pass 1a returned
+                // a valid envelope, which sets supported=true and disables this
+                // fallback. A batch that fails AFTER one has succeeded (flaky gateway
+                // mid-chunk) propagates as a real error instead — which matters,
+                // because replaying an already-applied Type PATCH would re-probe, see
+                // the new type, and report no typeChange for a conversion that did
+                // discard leaf values.
+                //
+                // tests/unit/batch-fallback-safety.test.ts pins both halves of this.
+                if (!(err instanceof BatchUnsupportedError))
+                    throw err;
+            }
+        }
+        return this.bulkUpsertPerRequest(dimensionName, hierarchyName, elements);
+    }
+    /**
+     * `$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.
+     */
+    async bulkUpsertViaBatch(dimensionName, hierarchyName, elements) {
+        const batch = this.batch;
+        const baseUrl = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements`;
+        // Correlate by element INDEX, not name: names are caller-supplied and could
+        // repeat, which would collapse two sub-responses onto one id.
+        const idOf = (i) => `e${i}`;
+        const indexOf = (id) => Number(id.slice(1));
+        // Pass 1a — create every element. TM1 runs the batch in payload order and
+        // continues past failures, so one response comes back per element.
+        const created = await batch.execute(elements.map((el, i) => ({
+            id: idOf(i),
+            method: "POST",
+            path: baseUrl,
+            body: { Name: el.name, Type: el.type },
+        })));
+        // Split the failures: "already exists" is the upsert path, anything else is
+        // a genuine error that must abort the whole op (same contract as the
+        // per-request path). Keep element order so the thrown error is the first
+        // failure in element order, not the first to be noticed.
+        const existing = [];
+        for (const r of created) {
+            if (r.ok)
+                continue;
+            const i = indexOf(r.id);
+            if (isAlreadyExists(r.error))
+                existing.push(i);
+            else
+                throw r.error;
+        }
+        // Pass 1b — read the current Type of the elements that already existed, so
+        // a type change can be reported (and skipped when it is a no-op). A failed
+        // probe means "type unreadable" and falls through to the unconditional
+        // PATCH below, matching the per-request path's behaviour on a NOT_FOUND.
+        const probed = await batch.execute(existing.map((i) => ({
+            id: idOf(i),
+            method: "GET",
+            path: `${baseUrl}('${enc(elements[i].name)}')?$select=Type`,
+        })));
+        const typeById = new Map();
+        for (const r of probed) {
+            // A transport/auth outage must NOT collapse into "type unreadable": that
+            // would silently PATCH the type below and discard the element's leaf cell
+            // values on a network blip or an expired session — and report nothing in
+            // typeChanges, because an unreadable prior type yields no entry. Same
+            // guard the per-request path applies to its probe; only a genuine,
+            // non-systemic failure (e.g. NOT_FOUND) may degrade to null.
+            if (!r.ok)
+                rethrowIfSystemic(r.error);
+            const raw = r.ok
+                ? r.body?.Type
+                : undefined;
+            typeById.set(indexOf(r.id), raw === undefined || raw === null ? null : normalizeElementType(raw));
+        }
+        // Pass 1c — patch the types that actually differ, plus the unreadable ones.
+        const typeChanges = [];
+        const patches = [];
+        for (const i of existing) {
+            const el = elements[i];
+            const from = typeById.get(i) ?? null;
+            if (from !== null && from === el.type)
+                continue;
+            patches.push({
+                id: idOf(i),
+                method: "PATCH",
+                path: `${baseUrl}('${enc(el.name)}')`,
+                body: { Type: el.type },
+            });
+            // A Numeric->Consolidated / Numeric->String conversion discards the
+            // element's leaf cell values, so report it rather than let it happen
+            // silently. An unreadable prior type yields no entry, as before.
+            if (from !== null)
+                typeChanges.push({ name: el.name, from, to: el.type });
+        }
+        throwFirstFailure(await batch.execute(patches), indexOf);
+        // Pass barrier: every leaf write above has settled before any consolidation
+        // references it via Components. Pass 1 already threw on any hard failure.
+        //
+        // Pass 2 — PATCH {Components:[...]} is FULL-REPLACE, not append (verified
+        // live vs TM1 v11). Consolidations with no/empty components are skipped, so
+        // an upsert that omits components leaves existing children intact.
+        const components = [];
+        for (const [i, el] of elements.entries()) {
+            if (el.type !== "Consolidated" ||
+                !el.components ||
+                el.components.length === 0)
+                continue;
+            components.push({
+                id: idOf(i),
+                method: "PATCH",
+                path: `${baseUrl}('${enc(el.name)}')`,
+                body: {
+                    Components: el.components.map((c) => ({
+                        "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(c.name)}')`,
+                        Weight: c.weight,
+                    })),
+                },
+            });
+        }
+        throwFirstFailure(await batch.execute(components), indexOf);
+        // Pass 3 — the weights. TM1 accepts `Weight` inside the Components link
+        // above and ignores it: every edge it creates has weight 1 (measured, see
+        // applyEdgeWeights). The weight lives on the Edge entity and has to be
+        // PATCHed once the link exists, which is only true after pass 2. Only
+        // deviating weights cost a request.
+        //
+        // Own id space: one element can own several edges, and a repeated id makes
+        // v12 reject the whole envelope. `edgeOwner` maps each request back to the
+        // element that asked for it, so a failure still names the right one.
+        const edges = [];
+        const edgeOwner = [];
+        for (const [i, el] of elements.entries()) {
+            if (el.type !== "Consolidated" || !el.components)
+                continue;
+            for (const c of el.components) {
+                if (c.weight === undefined || c.weight === 1)
+                    continue;
+                edges.push({
+                    id: `e${edgeOwner.length}`,
+                    method: "PATCH",
+                    path: `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Edges(ParentName='${enc(el.name)}',ComponentName='${enc(c.name)}')`,
+                    body: { Weight: c.weight },
+                });
+                edgeOwner.push(i);
+            }
+        }
+        if (edges.length > 0) {
+            throwFirstFailure(await batch.execute(edges), (id) => edgeOwner[Number(id.slice(1))] ?? Number.POSITIVE_INFINITY);
+        }
+        return { typeChanges };
+    }
+    /**
+     * Per-request fallback for bulkUpsert, used when the server has no `$batch`.
+     * Fans the calls out with bounded concurrency.
+     */
+    async bulkUpsertPerRequest(dimensionName, hierarchyName, elements) {
+        const baseUrl = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements`;
+        // Pass 1: Create/upsert all elements without components. Same-type element
+        // writes are independent, so fan them out with bounded concurrency instead
+        // of one serialized round-trip each (was 2-3N sequential calls). The cap
+        // keeps constant pressure on TM1's worker pool. Each unit returns its
+        // type-change (or null); we collect them index-aligned AFTER settle so
+        // typeChanges stays in stable element order regardless of completion order.
+        const pass1 = await mapSettledWithConcurrency(elements, BULK_UPSERT_CONCURRENCY, async (el) => {
+            const body = { Name: el.name, Type: el.type };
+            try {
+                await this.http.request("POST", baseUrl, body);
+                return null;
+            }
+            catch (err) {
+                if (err instanceof TM1Error && isAlreadyExists(err)) {
+                    // Element already exists. Patch the type only when it actually
+                    // differs (avoids a pointless write), and surface the change: a
+                    // Numeric->Consolidated / Numeric->String conversion discards the
+                    // element's leaf cell values, so the caller must be told it happened
+                    // rather than have it occur silently.
+                    const existing = await this.http
+                        .request("GET", `${baseUrl}('${enc(el.name)}')?$select=Type`)
+                        .catch((e) => {
+                        // A transport/auth outage here must NOT collapse into the
+                        // unconditional-PATCH branch below: that would silently change the
+                        // element type (discarding leaf values) on a network blip. Only a
+                        // genuine "type unreadable" (e.g. NOT_FOUND) may fall through to null.
+                        rethrowIfSystemic(e);
+                        return null;
+                    });
+                    const from = existing ? normalizeElementType(existing.Type) : null;
+                    if (from && from !== el.type) {
+                        await this.http.request("PATCH", `${baseUrl}('${enc(el.name)}')`, { Type: el.type });
+                        return { name: el.name, from, to: el.type };
+                    }
+                    if (!from) {
+                        // Type unreadable — preserve prior behaviour and patch unconditionally.
+                        await this.http.request("PATCH", `${baseUrl}('${enc(el.name)}')`, { Type: el.type });
+                    }
+                    return null;
+                }
+                throw err;
+            }
+        });
+        // Pass barrier: surface the first pass-1 failure (in element order) BEFORE
+        // any consolidation write. Pass 2 references leaves via Components, so it
+        // must not start until every leaf has settled — concurrency is safe within
+        // a pass but NOT across this barrier. Rejecting here preserves the prior
+        // "bulkUpsert throws if any element failed" contract.
+        const typeChanges = [];
+        for (const r of pass1) {
+            if (r.status === "rejected")
+                throw r.reason;
+            if (r.value)
+                typeChanges.push(r.value);
+        }
+        // Pass 2: Set components for consolidated elements.
+        // PATCH {Components:[...]} is FULL-REPLACE, not append (verified live vs
+        // TM1 v11: upserting [L3,L4] over existing [L1,L2] leaves the element with
+        // exactly {L3,L4}). Consolidations with no/empty components are skipped
+        // here, so an upsert that omits components leaves existing children intact
+        // — only a non-empty list rewrites the child set. Documented on the tool's
+        // `components` input so callers don't silently drop children. These writes
+        // are mutually independent (each targets a distinct element), so they fan
+        // out with the same bounded concurrency.
+        const consolidated = elements.filter((el) => el.type === "Consolidated" && el.components && el.components.length > 0);
+        const pass2 = await mapSettledWithConcurrency(consolidated, BULK_UPSERT_CONCURRENCY, async (el) => {
+            const path = `${baseUrl}('${enc(el.name)}')`;
+            const body = {
+                Components: el.components.map((c) => ({
+                    "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(c.name)}')`,
+                    Weight: c.weight,
+                })),
+            };
+            await this.http.request("PATCH", path, body);
+        });
+        for (const r of pass2) {
+            if (r.status === "rejected")
+                throw r.reason;
+        }
+        // Pass 3: the weights, for the same reason as the $batch path — TM1 takes
+        // `Weight` in the Components link and ignores it, so every edge lands at 1
+        // until it is PATCHed on the Edge entity. Runs after pass 2 because the
+        // edge has to exist first.
+        const pass3 = await mapSettledWithConcurrency(consolidated, BULK_UPSERT_CONCURRENCY, (el) => this.applyEdgeWeights(dimensionName, hierarchyName, el.name, el.components));
+        for (const r of pass3) {
+            if (r.status === "rejected")
+                throw r.reason;
+        }
+        return { typeChanges };
+    }
+    /**
+     * List element-attribute definitions for a hierarchy.
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/ElementAttributes
+     */
+    async listAttributes(dimensionName, hierarchyName) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/ElementAttributes`;
+        const response = await this.http.request("GET", path);
+        return response.value.map((a) => ({
+            name: a.Name,
+            type: a.Type,
+        }));
+    }
+    /**
+     * 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
+     */
+    async createAttribute(dimensionName, hierarchyName, attributeName, attributeType) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/ElementAttributes`;
+        await this.http.request("POST", path, {
+            Name: attributeName,
+            Type: attributeType,
+        });
+    }
+    /**
+     * Read all attribute values for one element via MDX on
+     * `}ElementAttributes_{Dim}`. Routes through CellService.executeMdx for the
+     * cellset round-trip.
+     */
+    async getAttributeValues(dimensionName, elementName) {
+        // Escape `]` → `]]` in every bracketed identifier: an element or dimension
+        // named e.g. `Foo]` would otherwise break out of its MDX identifier and
+        // shift the read onto arbitrary members (MDX injection).
+        const esc = (s) => s.replace(/]/g, "]]");
+        const dim = esc(dimensionName);
+        const elem = esc(elementName);
+        const ctrlCube = `}ElementAttributes_${dim}`;
+        const mdx = `SELECT {[}ElementAttributes_${dim}].MEMBERS} ON COLUMNS ` +
+            `FROM [${ctrlCube}] ` +
+            `WHERE ([${dim}].[${elem}])`;
+        const result = await this.cells.executeMdx(mdx);
+        const out = [];
+        const tuples = result.axes[0]?.tuples ?? [];
+        for (let i = 0; i < tuples.length; i++) {
+            const attrName = tuples[i].members[0]?.name ?? "";
+            const cell = result.cells[i];
+            out.push({
+                elementName,
+                attributeName: attrName,
+                value: cell?.value ?? null,
+            });
+        }
+        return out;
+    }
+    /**
+     * 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.
+     */
+    async getAttributeValuesPage(dimensionName, opts) {
+        const countPath = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(dimensionName)}')/Elements?$select=Name&$top=1&$count=true`;
+        const counted = await this.http.request("GET", countPath);
+        const total = counted["@odata.count"] ?? 0;
+        if (opts.limit === 0 || opts.offset >= total)
+            return { total, items: [] };
+        const esc = (s) => s.replace(/]/g, "]]");
+        const dim = esc(dimensionName);
+        const attrDim = `[}ElementAttributes_${dim}].[}ElementAttributes_${dim}]`;
+        const columns = opts.attributeNames && opts.attributeNames.length > 0
+            ? `{${opts.attributeNames.map((a) => `${attrDim}.[${esc(a)}]`).join(", ")}}`
+            : `{TM1SUBSETALL(${attrDim})}`;
+        const mdx = `SELECT ${columns} ON COLUMNS, ` +
+            `SUBSET(TM1SORT({TM1SUBSETALL([${dim}].[${dim}])}, ASC), ${opts.offset}, ${opts.limit}) ON ROWS ` +
+            `FROM [}ElementAttributes_${dim}]`;
+        const result = await this.cells.executeMdx(mdx);
+        const attrs = (result.axes[0]?.tuples ?? []).map((t) => t.members[0]?.name ?? "");
+        const rows = result.axes[1]?.tuples ?? [];
+        // Cells are row-major: cell (r, c) sits at r * columns + c.
+        const items = rows.map((t, r) => {
+            const values = {};
+            attrs.forEach((a, c) => {
+                values[a] = result.cells[r * attrs.length + c]?.value ?? null;
+            });
+            return { elementName: t.members[0]?.name ?? "", values };
+        });
+        return { total, items };
+    }
+    /**
+     * Set a single attribute value. See {@link updateAttributeValues}.
+     */
+    async updateAttributeValue(dimensionName, elementName, attributeName, value) {
+        await this.updateAttributeValues(dimensionName, [
+            { elementName, attributeName, value },
+        ]);
+    }
+    /**
+     * 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.
+     */
+    async updateAttributeValues(dimensionName, updates) {
+        if (updates.length === 0)
+            return;
+        const types = new Map((await this.listAttributes(dimensionName, dimensionName)).map((a) => [
+            a.name,
+            a.type,
+        ]));
+        const cells = updates.map((u) => {
+            const type = types.get(u.attributeName);
+            if (type === undefined) {
+                throw new TM1Error({
+                    code: TM1ErrorCode.VALIDATION_ERROR,
+                    message: `Attribute '${u.attributeName}' does not exist on dimension '${dimensionName}'.`,
+                    hint: `Known attributes: ${[...types.keys()].join(", ") || "(none)"}. Create it first with tm1_create_element_attribute.`,
+                });
+            }
+            let value = String(u.value);
+            if (type === "Numeric") {
+                const n = typeof u.value === "number" ? u.value : Number(u.value.trim());
+                if (u.value === "" || !Number.isFinite(n)) {
+                    throw new TM1Error({
+                        code: TM1ErrorCode.VALIDATION_ERROR,
+                        message: `Attribute '${u.attributeName}' is Numeric; '${String(u.value)}' (element '${u.elementName}') is not a number.`,
+                    });
+                }
+                value = n;
+            }
+            return { elements: [u.elementName, u.attributeName], value };
+        });
+        await this.cells.writeCells(`}ElementAttributes_${dimensionName}`, [dimensionName, `}ElementAttributes_${dimensionName}`], cells);
+    }
+}
+//# sourceMappingURL=element-service.js.map