Utilities

Result helpers, pagination helpers, endpoint catalogue exports, and dashboard endpoint analysis helpers.

Most projects can stay inside the domain services. These helpers are exported for scripts, tests, custom endpoint wrappers, and endpoint-discovery tooling.

Check whether a result failed

isLinxioFailure(result)

Narrows a LinxioResult<T> or LinxioPageResult<T> to its failure branch.

Input

LinxioResult<unknown> | LinxioPageResult<unknown>

required

SDK result object returned by a domain service.

Show child parameters

TData | null

optional

Returned data on success, or null on failure.

LinxioError | null

optional

Typed SDK error when the operation fails.

Returns

boolean

optional

True when result.error is not null.

Failure narrowing

import { isLinxioFailure } from "@ambulancewa/linxio-js";

const result = await linxio.vehicles.list({ limit: 100 });

if (isLinxioFailure(result)) {
  console.error(result.error.name, result.error.message);
  process.exitCode = 1;
}

Example response


{
  "data": true
}

Unwrap a result

unwrapLinxioResult(result)

Returns data from a successful result or throws the contained SDK error. Use this when your script prefers normal throwing control flow.

Input

LinxioResult<TData>

required

Non-paginated SDK result object.

Show child parameters

TData | null

optional

Returned data on success, or null on failure.

LinxioError | null

optional

Typed SDK error when the operation fails.

Returns

TData

optional

Successful result data.

LinxioError

optional

The contained SDK error when result.error is present.

Show child fields

string

required

Safe error message.

string

required

SDK error class name.

unknown

optional

Original cause when available.

string

optional

HTTP method when the error came from a request.

string

optional

API path when the error came from a request.

string

optional

Request identifier from X-Request-Id when supplied.

Unwrap result

import { unwrapLinxioResult } from "@ambulancewa/linxio-js";

const vehicle = unwrapLinxioResult(await linxio.vehicles.get(vehicleId));
console.log(vehicle.regNo);

Example response


{
  "data": "string"
}

Unwrap a page result

unwrapLinxioPageResult(result)

Returns a successful page result or throws the contained SDK error.

Input

LinxioPageResult<TData>

required

Paginated SDK result object.

Show child parameters

TData[] | null

optional

Records for the current page on success, or null on failure.

LinxioError | null

optional

Typed SDK error when the operation fails.

LinxioPaginationMeta | null

optional

Normalized pagination metadata on success.

number | null

optional

Current page number on success.

number | null

optional

Page size on success.

number | null

optional

Total matching record count on success.

unknown

optional

Aggregation payload when Linxio returns one.

Record<string, unknown>

optional

Additional page envelope fields retained by the SDK.

Returns

LinxioPageSuccess<TData>

optional

Successful page result with data, meta, page, limit, and total.

LinxioError

optional

The contained SDK error when result.error is present.

Show child fields

string

required

Safe error message.

string

required

SDK error class name.

unknown

optional

Original cause when available.

string

optional

HTTP method when the error came from a request.

string

optional

API path when the error came from a request.

string

optional

Request identifier from X-Request-Id when supplied.

Unwrap page

import { unwrapLinxioPageResult } from "@ambulancewa/linxio-js";

const page = unwrapLinxioPageResult(
  await linxio.vehicles.list({ limit: 100 }),
);

console.log(page.meta.total);

Example response


{
  "data": "string"
}

Convert unknown errors

toLinxioError(error)

Converts arbitrary thrown values into the SDK base error type.

Input

unknown

required

Unknown thrown value from user code or a custom integration.

Returns

LinxioError

optional

Existing LinxioError values are returned as-is; other values are wrapped.

Show child fields

string

required

Safe error message.

string

required

SDK error class name.

unknown

optional

Original cause when available.

string

optional

HTTP method when the error came from a request.

string

optional

API path when the error came from a request.

string

optional

Request identifier from X-Request-Id when supplied.

Normalize errors

import { toLinxioError } from "@ambulancewa/linxio-js";

try {
  await runCustomEndpoint();
} catch (error) {
  const linxioError = toLinxioError(error);
  console.error(linxioError.message);
}

Example response


{
  "data": {
    "message": "string",
    "name": "Example",
    "cause": {},
    "method": "string",
    "path": "string",
    "requestId": "string"
  }
}

Create result objects

ok(data); fail(error); pageOk(page); pageFail(error)

Builds SDK-shaped result objects for custom services or tests.

Helpers

LinxioSuccess<TData>

optional

Creates a successful non-paginated result.

LinxioFailure<LinxioError>

optional

Creates a failed non-paginated result from an unknown error.

Show child fields

string

required

Safe error message.

string

required

SDK error class name.

unknown

optional

Original cause when available.

string

optional

HTTP method when the error came from a request.

string

optional

API path when the error came from a request.

string

optional

Request identifier from X-Request-Id when supplied.

LinxioPageSuccess<TData>

optional

Creates a successful paginated result from a normalized page.

LinxioPageFailure<LinxioError>

optional

Creates a failed paginated result from an unknown error.

Show child fields

string

required

Safe error message.

string

required

SDK error class name.

unknown

optional

Original cause when available.

string

optional

HTTP method when the error came from a request.

string

optional

API path when the error came from a request.

string

optional

Request identifier from X-Request-Id when supplied.

Custom result

import { fail, ok } from "@ambulancewa/linxio-js";

async function readCustomThing() {
  try {
    return ok(await linxio.request("GET", "/custom-thing"));
  } catch (error) {
    return fail(error);
  }
}

Collect pages

collectPages(loadPage, params)

Loads every page from a paginated endpoint into a single result object. Domain services already wrap this for common list methods.

Input

(params: TParams) => Promise<LinxioPageResult<TData>>

required

Function that loads one page.

Show child parameters

TData[] | null

optional

Records for the current page on success, or null on failure.

LinxioError | null

optional

Typed SDK error when the operation fails.

LinxioPaginationMeta | null

optional

Normalized pagination metadata on success.

number | null

optional

Current page number on success.

number | null

optional

Page size on success.

number | null

optional

Total matching record count on success.

unknown

optional

Aggregation payload when Linxio returns one.

Record<string, unknown>

optional

Additional page envelope fields retained by the SDK.

TParams

optional

Initial list parameters. limit controls page size.

Returns

LinxioResult<TData[]>

optional

All records from all pages, or a typed SDK error.

Show child fields

TData | null

optional

Returned data on success, or null on failure.

LinxioError | null

optional

Typed SDK error when the operation fails.

Collect custom endpoint pages

import { collectPages } from "@ambulancewa/linxio-js";

const result = await collectPages(
  (params) => linxio.sensors.list(params),
  { limit: 100 },
);

if (result.error) {
  throw result.error;
}

Example response


{
  "data": {
    "data": "string",
    "error": null
  }
}

Stream pages

streamPages(loadPage, params)

Streams a paginated endpoint one item at a time. This helper throws if a page fails.

Input

(params: TParams) => Promise<LinxioPageResult<TData>>

required

Function that loads one page.

Show child parameters

TData[] | null

optional

Records for the current page on success, or null on failure.

LinxioError | null

optional

Typed SDK error when the operation fails.

LinxioPaginationMeta | null

optional

Normalized pagination metadata on success.

number | null

optional

Current page number on success.

number | null

optional

Page size on success.

number | null

optional

Total matching record count on success.

unknown

optional

Aggregation payload when Linxio returns one.

Record<string, unknown>

optional

Additional page envelope fields retained by the SDK.

TParams

optional

Initial list parameters. limit controls page size.

Returns

TData

optional

One item at a time across all pages.

LinxioError

optional

Thrown when any page fails.

Show child fields

string

required

Safe error message.

string

required

SDK error class name.

unknown

optional

Original cause when available.

string

optional

HTTP method when the error came from a request.

string

optional

API path when the error came from a request.

string

optional

Request identifier from X-Request-Id when supplied.

Stream custom endpoint pages

import { streamPages } from "@ambulancewa/linxio-js";

for await (const sensor of streamPages(
  (params) => linxio.sensors.list(params),
  { limit: 100 },
)) {
  console.log(sensor.id, sensor.label);
}

Example response


{
  "yield": "string"
}

Use the endpoint catalogue

linxioEndpoints

Runtime catalogue of public and dashboard-derived endpoints represented by the SDK.

Endpoint definition

GET | POST | PATCH | PUT | DELETE

optional

HTTP method.

string

optional

Endpoint path. Dynamic segments use {name} placeholders.

public-docs | dashboard

optional

Whether the endpoint is from Linxio's public API docs or inferred from dashboard JavaScript.

Flatten endpoint definitions

flattenEndpointDefinitions(catalogue)

Converts the nested endpoint catalogue into a sorted array of endpoint definitions.

Input

unknown

required

Nested endpoint catalogue, usually linxioEndpoints.

Returns

LinxioEndpointDefinition[]

optional

Sorted endpoint definitions.

Flatten endpoints

import { flattenEndpointDefinitions, linxioEndpoints } from "@ambulancewa/linxio-js";

const endpoints = flattenEndpointDefinitions(linxioEndpoints);
console.table(endpoints.slice(0, 5));

Example response


{
  "data": [
    "string"
  ]
}

Extract dashboard endpoints

extractDashboardEndpoints(sources)

Extracts endpoint evidence from captured Linxio dashboard JavaScript bundles.

Input

DashboardSourceFile[]

required

Source filename and JavaScript content pairs.

Returns

DashboardEndpointEvidence[]

optional

Endpoint candidates with methods, files, occurrence counts, and normalized paths.

Extract dashboard endpoint evidence

import { extractDashboardEndpoints } from "@ambulancewa/linxio-js";

const endpoints = extractDashboardEndpoints([
  {
    filename: "main.js",
    content: dashboardBundle,
  },
]);

Example response


{
  "data": [
    "string"
  ]
}

Compare endpoint coverage

compareDashboardEndpointCoverage(input)

Compares dashboard-extracted endpoint evidence with SDK endpoint definitions.

Input

DashboardEndpointEvidence[]

required

Endpoint evidence from extractDashboardEndpoints().

LinxioEndpointDefinition[]

required

Flattened SDK endpoint definitions.

Returns

DashboardEndpointEvidence[]

optional

Dashboard-observed endpoints represented in the SDK catalogue.

DashboardEndpointEvidence[]

optional

Dashboard-observed endpoints not represented in the SDK catalogue.

LinxioEndpointDefinition[]

optional

SDK catalogue endpoints not observed in the analysed dashboard bundle set.

Compare coverage

import {
  compareDashboardEndpointCoverage,
  extractDashboardEndpoints,
  flattenEndpointDefinitions,
  linxioEndpoints,
} from "@ambulancewa/linxio-js";

const coverage = compareDashboardEndpointCoverage({
  dashboardEndpoints: extractDashboardEndpoints(sources),
  sdkEndpoints: flattenEndpointDefinitions(linxioEndpoints),
});

console.log(coverage.dashboardOnly);

Example response


{
  "dashboardCovered": [
    "string"
  ],
  "dashboardOnly": [
    "string"
  ],
  "sdkOnly": [
    "string"
  ]
}

Utilities

Check whether a result failed

Input

Returns

Unwrap a result

Input

Returns

Unwrap a page result

Input

Returns

Convert unknown errors

Input

Returns

Create result objects

Helpers

Collect pages

Input

Returns

Stream pages

Input

Returns

Use the endpoint catalogue

Endpoint definition

Flatten endpoint definitions

Input

Returns

Extract dashboard endpoints

Input

Returns

Compare endpoint coverage

Input

Returns

On this page