@ffschrattenecker/tm1-mcp-server 6.0.0

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

@@ -0,0 +1,332 @@
+// Hierarchy domain service. Owns the OData calls under
+// /api/v1/Dimensions('{d}')/Hierarchies(...) — get, create, delete, plus the
+// derived ancestors/descendants traversals that fetch a hierarchy and walk it
+// client-side. See docs/ARCHITECTURE.md for the layering.
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+import { compileUserRegex } from "../../lib/safe-regex.js";
+import { pageClauseList, readNestedCount } from "./odata-page.js";
+// OData key encoder: double ' per OData literal rules, then percent-encode.
+const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+// elementType pushes down as the ORDINAL, not the name: `Type eq
+// 'Consolidated'` is accepted and matches nothing — silently, which is
+// worse than an error and is why this filter used to run client-side.
+// `Type eq 3` works (verified live on 11.8: 1 → Numeric, 2 → String,
+// 3 → Consolidated).
+//
+// Doing it server-side matters more since elements carry their Edges: a
+// client-side type filter means fetching every element of the dimension
+// with its edges attached — measured at 99 MB on a 171k-element dimension,
+// against 300 KB for the pushed-down page.
+//
+// nameRegex stays client-side; OData has no regex.
+const TYPE_ORDINAL = {
+    Numeric: 1,
+    String: 2,
+    Consolidated: 3,
+};
+function elementFilters(opts) {
+    const filters = [];
+    if (opts?.level !== undefined)
+        filters.push(`Level eq ${opts.level}`);
+    if (opts?.levelMax !== undefined)
+        filters.push(`Level le ${opts.levelMax}`);
+    const escapeOdata = (s) => s.replace(/'/g, "''");
+    if (opts?.nameContains)
+        filters.push(`contains(Name, '${escapeOdata(opts.nameContains)}')`);
+    if (opts?.nameStartsWith)
+        filters.push(`startswith(Name, '${escapeOdata(opts.nameStartsWith)}')`);
+    const typeOrdinal = opts?.elementType && opts.elementType !== "All"
+        ? TYPE_ORDINAL[opts.elementType]
+        : undefined;
+    if (typeOrdinal !== undefined)
+        filters.push(`Type eq ${typeOrdinal}`);
+    const regex = opts?.nameRegex !== undefined
+        ? compileUserRegex(opts.nameRegex, undefined, "nameRegex")
+        : undefined;
+    return { filters, regex };
+}
+export class HierarchyService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Get a specific hierarchy with its elements, including parent/child
+     * relationships. TM1 11.8 does not expose `Children` on Element, only
+     * `Parents` — children are derived client-side. Filtered-out parents are
+     * removed from the surviving elements' parents/children arrays to avoid
+     * dangling references.
+     *
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')?$expand=Elements(...)
+     *
+     * Paging: when no client-side post-filter is needed, `topN`/`skip` are
+     * pushed into the nested Elements expand together with `$orderby=Name` and
+     * `$count=true`. On a live 211k-element dimension that is 48 KB/page against
+     * 67 MB for the unbounded fetch. `$orderby` is not optional — without it
+     * `$skip` walks TM1's internal index order, which shifts on every element
+     * create/delete and would duplicate or drop elements between pages.
+     */
+    async get(dimensionName, hierarchyName, opts) {
+        const elementClauses = [
+            "$select=Name,Type,Level",
+            // Parents for the tree, Edges for the child weights. Both are element
+            // navigations, so one request answers both — see the weight join below
+            // for why the separate Edges scan is gone.
+            "$expand=Parents($select=Name),Edges($select=ComponentName,Weight)",
+        ];
+        const { filters, regex } = elementFilters(opts);
+        const needsClientPostFilter = regex !== undefined;
+        if (filters.length > 0)
+            elementClauses.push(`$filter=${filters.join(" and ")}`);
+        const skip = opts?.skip ?? 0;
+        const topN = opts?.topN;
+        // Push the window down only when nothing is filtered afterwards. With a
+        // client post-filter active, `Elements@odata.count` would count rows the
+        // caller never sees, so both the window and the total have to be computed
+        // here, on the filtered set.
+        const pushDown = topN !== undefined && !needsClientPostFilter;
+        if (pushDown)
+            elementClauses.push(...pageClauseList({ top: topN, skip }));
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')?$expand=Elements(${elementClauses.join(";")})`;
+        const rawResponse = await this.http.request("GET", path);
+        let filteredElements = rawResponse.Elements;
+        if (regex !== undefined)
+            filteredElements = filteredElements.filter((e) => regex.test(e.Name));
+        // Total of everything the filters kept, before the window is applied.
+        // Server-side count when it was pushed down; otherwise the post-filter
+        // length, which is exact because we hold the whole filtered set.
+        let totalElements = pushDown
+            ? (readNestedCount(rawResponse, "Elements") ??
+                skip + filteredElements.length)
+            : filteredElements.length;
+        if (!pushDown && (skip > 0 || topN !== undefined)) {
+            filteredElements = filteredElements.slice(skip, skip + (topN ?? filteredElements.length));
+        }
+        // A count below what we already hold means the hierarchy shrank between
+        // count and slice — trust the rows in hand.
+        totalElements = Math.max(totalElements, skip + filteredElements.length);
+        const response = { Name: rawResponse.Name, Elements: filteredElements };
+        const keptNames = new Set(response.Elements.map((e) => e.Name));
+        // Edge weights ride along with the elements: `Element` has an `Edges`
+        // navigation carrying its OUTGOING edges — its children, with weights —
+        // so the page already fetched above answers the question. Verified live:
+        // every consolidated row's edges had ParentName equal to that row, and no
+        // row carried an edge belonging to anything else.
+        //
+        // The alternative this replaces was reading the hierarchy's whole `Edges`
+        // collection: 21.6 MB and 594 ms for a 171k-element dimension, against
+        // 309 KB and 98 ms for the page-with-edges — one round trip instead of
+        // two, and bounded by the page's fan-out rather than by the dimension.
+        //
+        // A missing edge still falls back to 1, TM1's default. That fallback is
+        // why tests/live/dimension.live.test.ts pins a weight of -1: with 1 there
+        // is no way to tell a weight that was read from one that was invented.
+        const weightByEdge = new Map();
+        for (const e of response.Elements) {
+            for (const edge of e.Edges ?? []) {
+                let byChild = weightByEdge.get(e.Name);
+                if (!byChild) {
+                    byChild = new Map();
+                    weightByEdge.set(e.Name, byChild);
+                }
+                byChild.set(edge.ComponentName, edge.Weight);
+            }
+        }
+        const childrenByParent = new Map();
+        for (const e of response.Elements) {
+            for (const p of e.Parents ?? []) {
+                if (!keptNames.has(p.Name))
+                    continue;
+                const list = childrenByParent.get(p.Name) ?? [];
+                list.push({
+                    name: e.Name,
+                    weight: weightByEdge.get(p.Name)?.get(e.Name) ?? 1,
+                });
+                childrenByParent.set(p.Name, list);
+            }
+        }
+        const elements = response.Elements.map((e) => ({
+            name: e.Name,
+            type: e.Type,
+            level: e.Level,
+            parents: (e.Parents ?? [])
+                .filter((p) => keptNames.has(p.Name))
+                .map((p) => p.Name),
+            children: childrenByParent.get(e.Name) ?? [],
+        }));
+        return {
+            name: response.Name,
+            dimensionName,
+            elements,
+            totalElements,
+        };
+    }
+    /**
+     * Element totals by type and level for a (filtered) hierarchy — no element
+     * rows. Reads the Elements collection with `$select=Type,Level` (plus Name
+     * only when a regex has to run client-side), so a count over a 200k-element
+     * dimension costs a few MB of wire traffic and a few hundred bytes of reply,
+     * where probing with growing `topN` returned the elements themselves.
+     *
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements?$select=Type,Level
+     */
+    async getCounts(dimensionName, hierarchyName, opts) {
+        const { filters, regex } = elementFilters(opts);
+        const clauses = [regex ? "$select=Name,Type,Level" : "$select=Type,Level"];
+        if (filters.length > 0)
+            clauses.push(`$filter=${filters.join(" and ")}`);
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')` +
+            `/Elements?${clauses.join("&")}`;
+        const response = await this.http.request("GET", path);
+        let rows = response.value ?? [];
+        if (regex !== undefined)
+            rows = rows.filter((e) => regex.test(e.Name ?? ""));
+        const counts = {
+            total: rows.length,
+            byType: { Numeric: 0, String: 0, Consolidated: 0 },
+            byLevel: {},
+            maxLevel: 0,
+        };
+        for (const e of rows) {
+            if (e.Type === "Numeric" ||
+                e.Type === "String" ||
+                e.Type === "Consolidated")
+                counts.byType[e.Type]++;
+            const lvl = String(e.Level);
+            counts.byLevel[lvl] = (counts.byLevel[lvl] ?? 0) + 1;
+            if (e.Level > counts.maxLevel)
+                counts.maxLevel = e.Level;
+        }
+        return counts;
+    }
+    /**
+     * Element name + type for a whole hierarchy — nothing else.
+     *
+     * `get()` is the wrong tool for a type lookup: it expands `Parents` and
+     * `Edges` on every element to build the tree and weight the children. This
+     * reads the Elements collection directly with `$select=Name,Type` — no
+     * expand at all — which is the minimum payload for name → type resolution.
+     *
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements?$select=Name,Type
+     */
+    async getElementTypes(dimensionName, hierarchyName) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')` +
+            `/Elements?$select=Name,Type`;
+        const response = await this.http.request("GET", path);
+        return (response.value ?? []).map((e) => ({
+            name: e.Name,
+            type: e.Type,
+        }));
+    }
+    /**
+     * Resolve descendants of a consolidation element via client-side BFS over
+     * the full hierarchy. Returns a flat list with depth from the start element.
+     * Reuses get() — REST traffic identical, but the LLM-facing payload is a
+     * focused subtree, not the whole dimension.
+     */
+    async getDescendants(dimensionName, hierarchyName, element, opts) {
+        const hierarchy = await this.get(dimensionName, hierarchyName);
+        const byName = new Map();
+        for (const e of hierarchy.elements)
+            byName.set(e.name, e);
+        if (!byName.has(element)) {
+            throw new TM1Error({
+                code: TM1ErrorCode.NOT_FOUND,
+                message: `Element '${element}' not found in ${dimensionName}.${hierarchyName}`,
+            });
+        }
+        const out = [];
+        const seen = new Set([element]);
+        const queue = [
+            { name: element, depth: 0 },
+        ];
+        while (queue.length > 0) {
+            const cur = queue.shift();
+            const node = byName.get(cur.name);
+            if (!node)
+                continue;
+            const nextDepth = cur.depth + 1;
+            if (opts?.depth !== undefined && nextDepth > opts.depth)
+                continue;
+            for (const child of node.children) {
+                if (seen.has(child.name))
+                    continue;
+                seen.add(child.name);
+                const childNode = byName.get(child.name);
+                if (!childNode)
+                    continue;
+                const isLeaf = childNode.children.length === 0;
+                if (!opts?.leavesOnly || isLeaf) {
+                    out.push({
+                        name: childNode.name,
+                        type: childNode.type,
+                        level: childNode.level,
+                        depth: nextDepth,
+                    });
+                }
+                queue.push({ name: child.name, depth: nextDepth });
+            }
+        }
+        return { element, descendants: out };
+    }
+    /**
+     * Resolve ancestors of an element via parent-walk. Handles multi-parent
+     * hierarchies — returns the unique flat ancestor set AND every distinct
+     * root-to-element path so consumers can see consolidation alternatives.
+     */
+    async getAncestors(dimensionName, hierarchyName, element) {
+        const hierarchy = await this.get(dimensionName, hierarchyName);
+        const byName = new Map();
+        for (const e of hierarchy.elements)
+            byName.set(e.name, e);
+        if (!byName.has(element)) {
+            throw new TM1Error({
+                code: TM1ErrorCode.NOT_FOUND,
+                message: `Element '${element}' not found in ${dimensionName}.${hierarchyName}`,
+            });
+        }
+        const ancestorMap = new Map();
+        const paths = [];
+        const walk = (name, currentPath, visited) => {
+            const node = byName.get(name);
+            if (!node)
+                return;
+            const parents = node.parents;
+            if (parents.length === 0) {
+                paths.push([...currentPath]);
+                return;
+            }
+            for (const parentName of parents) {
+                if (visited.has(parentName))
+                    continue;
+                const parentNode = byName.get(parentName);
+                if (!parentNode)
+                    continue;
+                ancestorMap.set(parentName, parentNode.level);
+                const nextVisited = new Set(visited);
+                nextVisited.add(parentName);
+                walk(parentName, [...currentPath, parentName], nextVisited);
+            }
+        };
+        walk(element, [element], new Set([element]));
+        const ancestors = [...ancestorMap.entries()]
+            .map(([name, level]) => ({ name, level }))
+            .sort((a, b) => a.level - b.level || a.name.localeCompare(b.name));
+        return { element, ancestors, paths };
+    }
+    /**
+     * Create a new hierarchy inside an existing dimension.
+     * POST /api/v1/Dimensions('{d}')/Hierarchies
+     */
+    async create(dimensionName, hierarchyName) {
+        await this.http.request("POST", `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies`, { Name: hierarchyName });
+    }
+    /**
+     * Delete a hierarchy from a dimension.
+     * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')
+     */
+    async delete(dimensionName, hierarchyName) {
+        await this.http.request("DELETE", `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')`);
+    }
+}
+//# sourceMappingURL=hierarchy-service.js.map

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

@@ -0,0 +1,34 @@
+import type { Job, Session, Thread } from "../../types.js";
+import type { TM1HttpClient } from "../http.js";
+export declare class MonitoringService {
+    private readonly http;
+    constructor(http: TM1HttpClient);
+    /**
+     * List all active threads on the TM1 server.
+     * GET /api/v1/Threads
+     */
+    getThreads(): Promise<Thread[]>;
+    /**
+     * Cancel a running TM1 server thread.
+     * POST /api/v1/Threads({id})/tm1.CancelOperation
+     */
+    cancelThread(threadId: number): Promise<void>;
+    /**
+     * List all active sessions on the TM1 server with associated user and
+     * threads. TM1 v11.8 returns ID as number; v12 as string — coerced to
+     * string. Numeric Type codes are mapped to symbolic names where known.
+     * GET /api/v1/Sessions?$expand=Threads,User($select=Name)
+     */
+    getSessions(): Promise<Session[]>;
+    /**
+     * List all active jobs on v12 database replica.
+     * GET /api/v1/Jobs?$select=ID,Description,State,ElapsedTime,WaitTime&$expand=Session,WaitingOn
+     */
+    getJobs(): Promise<Job[]>;
+    /**
+     * Cancel running v12 job.
+     * POST /api/v1/Jobs('{id}')/tm1.Cancel
+     */
+    cancelJob(jobId: string): Promise<void>;
+}
+//# sourceMappingURL=monitoring-service.d.ts.map

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

@@ -0,0 +1,123 @@
+function encKey(s) {
+    // Double single-quotes for OData escaping, then percent-encode all URL-unsafe chars
+    return encodeURIComponent(String(s).replace(/'/g, "''")).replace(/'/g, "%27");
+}
+export class MonitoringService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List all active threads on the TM1 server.
+     * GET /api/v1/Threads
+     */
+    async getThreads() {
+        const response = await this.http.request("GET", "/api/v1/Threads?$select=ID,Type,Name,Context,State,Function,ObjectName,ElapsedTime");
+        const typeNames = {
+            1: "User",
+            2: "System",
+            4: "Admin",
+            8: "Chore",
+            16: "Extern",
+        };
+        return (response.value ?? []).map((t) => ({
+            id: t.ID,
+            type: typeNames[t.Type] ?? `Type${t.Type}`,
+            name: t.Name,
+            state: t.State,
+            function: t.Function,
+            objectName: t.ObjectName,
+            elapsedTime: t.ElapsedTime,
+            context: t.Context,
+        }));
+    }
+    /**
+     * Cancel a running TM1 server thread.
+     * POST /api/v1/Threads({id})/tm1.CancelOperation
+     */
+    async cancelThread(threadId) {
+        await this.http.request("POST", `/api/v1/Threads(${threadId})/tm1.CancelOperation`, {});
+    }
+    /**
+     * List all active sessions on the TM1 server with associated user and
+     * threads. TM1 v11.8 returns ID as number; v12 as string — coerced to
+     * string. Numeric Type codes are mapped to symbolic names where known.
+     * GET /api/v1/Sessions?$expand=Threads,User($select=Name)
+     */
+    async getSessions() {
+        const response = await this.http.request("GET", "/api/v1/Sessions?$expand=Threads,User($select=Name)");
+        const typeNames = {
+            1: "User",
+            2: "System",
+            4: "Admin",
+            8: "Chore",
+            16: "Extern",
+        };
+        return (response.value ?? []).map((s) => ({
+            id: String(s.ID),
+            user: s.User?.Name ?? "",
+            ...(s.Active !== undefined ? { active: s.Active } : {}),
+            threads: (s.Threads ?? []).map((t) => ({
+                id: t.ID,
+                type: typeof t.Type === "number"
+                    ? (typeNames[t.Type] ?? `Type${t.Type}`)
+                    : (t.Type ?? ""),
+                name: t.Name ?? "",
+                state: t.State ?? "",
+                function: t.Function ?? "",
+                objectName: t.ObjectName ?? "",
+                ...(t.ObjectType !== undefined ? { objectType: t.ObjectType } : {}),
+                ...(t.ElapsedTime !== undefined ? { elapsedTime: t.ElapsedTime } : {}),
+                ...(t.WaitTime !== undefined ? { waitTime: t.WaitTime } : {}),
+                ...(t.Info !== undefined ? { info: t.Info } : {}),
+            })),
+        }));
+    }
+    /**
+     * List all active jobs on v12 database replica.
+     * GET /api/v1/Jobs?$select=ID,Description,State,ElapsedTime,WaitTime&$expand=Session,WaitingOn
+     */
+    async getJobs() {
+        // Fields below are typed loosely to match observed reality: the PA Engine
+        // can send `null` (not just omit) for any of these, and IDs have been seen
+        // as both string and number. Mapping below is null/undefined-safe.
+        const response = await this.http.request("GET", "/api/v1/Jobs?$select=ID,Description,State,ElapsedTime,WaitTime&$expand=Session($select=ID,Context;$expand=User($select=Name)),WaitingOn($select=ID,Description,State)");
+        return (response.value ?? []).map((j) => ({
+            id: String(j.ID),
+            description: j.Description ?? "",
+            state: j.State ?? "",
+            ...(j.ElapsedTime != null ? { elapsedTime: j.ElapsedTime } : {}),
+            ...(j.WaitTime != null ? { waitTime: j.WaitTime } : {}),
+            ...(j.Session
+                ? {
+                    session: {
+                        id: String(j.Session.ID),
+                        ...(j.Session.Context != null
+                            ? { context: j.Session.Context }
+                            : {}),
+                        ...(j.Session.User?.Name != null
+                            ? { user: j.Session.User.Name }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...(j.WaitingOn
+                ? {
+                    waitingOn: j.WaitingOn.map((w) => ({
+                        id: String(w.ID),
+                        description: w.Description ?? "",
+                        state: w.State ?? "",
+                    })),
+                }
+                : {}),
+        }));
+    }
+    /**
+     * Cancel running v12 job.
+     * POST /api/v1/Jobs('{id}')/tm1.Cancel
+     */
+    async cancelJob(jobId) {
+        await this.http.request("POST", `/api/v1/Jobs('${encKey(jobId)}')/tm1.Cancel`, {});
+    }
+}
+//# sourceMappingURL=monitoring-service.js.map

package/dist/tm1-client/services/odata-page.d.ts

@@ -0,0 +1,71 @@
+export interface PageOpts {
+    /** `$top` — page size. Positive integer (comes from a Zod-validated `limit`). */
+    top: number;
+    /** `$skip` — items to skip. Non-negative integer (Zod-validated `offset`). */
+    skip: number;
+    /** `$orderby` property. Service-internal literal, never caller input. Default `Name`. */
+    orderBy?: string;
+}
+/** Result of a pushed-down list call. */
+export interface Paged<T> {
+    items: T[];
+    /** `@odata.count`; undefined when the server omitted it (caller must fall back). */
+    total: number | undefined;
+}
+/**
+ * The paging clauses as separate `$…=…` fragments, in a fixed order.
+ * Returns `[]` when no page was requested.
+ *
+ * Use this for nested `$expand(...)` option lists (joined with `;`);
+ * use {@link pageClauses} for top-level query strings (joined with `&`).
+ */
+export declare function pageClauseList(page: PageOpts | undefined): string[];
+/**
+ * Top-level paging clauses with a leading `&`, ready to append to a query
+ * string that already has at least one parameter. Empty string when unpaged.
+ */
+export declare function pageClauses(page: PageOpts | undefined): string;
+/** Read the collection-level `@odata.count` a `$count=true` request adds. */
+export declare function readCount(response: {
+    "@odata.count"?: number;
+} | null | undefined): number | undefined;
+/**
+ * Read the `<Nav>@odata.count` that a nested `$expand=Nav($count=true)` adds to
+ * the *parent* entity (TM1 hangs the count off the owner, not the array).
+ */
+export declare function readNestedCount(response: Record<string, unknown> | null | undefined, navigationProperty: string): number | undefined;
+/** Double `'` per OData literal rules so a caller string cannot break out of a literal. */
+export declare function escapeOdataLiteral(value: string): string;
+/** Join filter predicates with `and` into a `&$filter=…` fragment. Empty string when none. */
+export declare function filterClause(predicates: readonly string[]): string;
+/**
+ * Name-based predicates the `/Cubes`, `/Dimensions` and `/Processes` listings
+ * share. Only filters TM1 can evaluate itself belong here — a filter that
+ * stays client-side must disable push-down entirely, or `@odata.count` (and
+ * with it `total`/`has_more`) over-reports.
+ *
+ * `nameExact` uses `eq`, which TM1 evaluates case-sensitively — same semantics
+ * as the handlers' client-side `===`. `nameContains`/`nameNotContains` are
+ * case-insensitive via `tolower`, matching the handlers' `toLowerCase()`.
+ */
+export interface NameFilterOpts {
+    /** false ⇒ exclude `}`-prefixed control objects. */
+    includeControl?: boolean;
+    nameExact?: string;
+    nameContains?: string;
+    nameNotContains?: string;
+}
+export declare function nameFilterPredicates(opts: NameFilterOpts): string[];
+/**
+ * Ordinal (UTF-16 code-unit) name comparator. TM1's `$orderby=Name` was
+ * live-probed against a 340-dimension / 319-process / 121-cube model and
+ * matched this ordering exactly, so the client-side fallback path can present
+ * the same order as the pushed-down path. Do not swap in `localeCompare` —
+ * it collates case- and accent-insensitively and would diverge.
+ */
+export declare function compareByName(a: {
+    name: string;
+}, b: {
+    name: string;
+}): number;
+//# sourceMappingURL=odata-page.d.ts.map

package/dist/tm1-client/services/odata-page.js

@@ -0,0 +1,87 @@
+// Shared OData paging/filter clause builder for server-side $top/$skip
+// push-down.
+//
+// Lives in the service layer on purpose: `lint:no-flat-api` keeps every OData
+// query fragment inside a service, so handlers pass semantic options
+// ({page, nameContains, includeControl}) and the service turns them into a
+// query string. Nothing here interpolates a caller string without escaping it.
+//
+// Why the clauses always travel together:
+//   $orderby — mandatory. `$skip` without a stable sort is undefined in OData;
+//              TM1 answers in internal index order, which shifts whenever an
+//              object is created or deleted, so a two-page walk would silently
+//              duplicate or drop rows.
+//   $count   — the server-side total *after* $filter, which is what the
+//              Page<T> envelope's `total` means. Callers must therefore only
+//              push down when every active filter is expressible in OData.
+/**
+ * The paging clauses as separate `$…=…` fragments, in a fixed order.
+ * Returns `[]` when no page was requested.
+ *
+ * Use this for nested `$expand(...)` option lists (joined with `;`);
+ * use {@link pageClauses} for top-level query strings (joined with `&`).
+ */
+export function pageClauseList(page) {
+    if (page === undefined)
+        return [];
+    return [
+        `$orderby=${page.orderBy ?? "Name"}`,
+        `$top=${page.top}`,
+        `$skip=${page.skip}`,
+        "$count=true",
+    ];
+}
+/**
+ * Top-level paging clauses with a leading `&`, ready to append to a query
+ * string that already has at least one parameter. Empty string when unpaged.
+ */
+export function pageClauses(page) {
+    const list = pageClauseList(page);
+    return list.length === 0 ? "" : `&${list.join("&")}`;
+}
+/** Read the collection-level `@odata.count` a `$count=true` request adds. */
+export function readCount(response) {
+    return response?.["@odata.count"];
+}
+/**
+ * Read the `<Nav>@odata.count` that a nested `$expand=Nav($count=true)` adds to
+ * the *parent* entity (TM1 hangs the count off the owner, not the array).
+ */
+export function readNestedCount(response, navigationProperty) {
+    const raw = response?.[`${navigationProperty}@odata.count`];
+    return typeof raw === "number" ? raw : undefined;
+}
+/** Double `'` per OData literal rules so a caller string cannot break out of a literal. */
+export function escapeOdataLiteral(value) {
+    return value.replace(/'/g, "''");
+}
+/** Join filter predicates with `and` into a `&$filter=…` fragment. Empty string when none. */
+export function filterClause(predicates) {
+    return predicates.length === 0 ? "" : `&$filter=${predicates.join(" and ")}`;
+}
+export function nameFilterPredicates(opts) {
+    const predicates = [];
+    if (opts.includeControl !== true)
+        predicates.push("not startswith(Name,'}')");
+    if (opts.nameExact !== undefined && opts.nameExact.length > 0) {
+        predicates.push(`Name eq '${escapeOdataLiteral(opts.nameExact)}'`);
+    }
+    if (opts.nameContains !== undefined && opts.nameContains.length > 0) {
+        predicates.push(`contains(tolower(Name),'${escapeOdataLiteral(opts.nameContains.toLowerCase())}')`);
+    }
+    if (opts.nameNotContains !== undefined && opts.nameNotContains.length > 0) {
+        predicates.push(`not contains(tolower(Name),'${escapeOdataLiteral(opts.nameNotContains.toLowerCase())}')`);
+    }
+    return predicates;
+}
+/**
+ * Ordinal (UTF-16 code-unit) name comparator. TM1's `$orderby=Name` was
+ * live-probed against a 340-dimension / 319-process / 121-cube model and
+ * matched this ordering exactly, so the client-side fallback path can present
+ * the same order as the pushed-down path. Do not swap in `localeCompare` —
+ * it collates case- and accent-insensitively and would diverge.
+ */
+export function compareByName(a, b) {
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+//# sourceMappingURL=odata-page.js.map