claviz-liminal-qlik

A Qlik Engine gateway that pools sessions and provides an enigma-compatible Node SDK.

Overview

• One Engine session per userId + appId, shared across callers (in-flight open de-dupe).
• Caches common app objects (objects, fields, variables, measures) to reduce duplicate calls.
• Broadcasts changed (optional layout) and synthetic loading events to all subscribers.
• Node client SDK that exposes enigma-style proxies.

Server

Quick start

npm install
npm run build
npm start

Defaults:

• HTTP: http://localhost:1337
• Health: GET /health

Configuration (env + programmatic)

dotenv-flow loads .env*. startServer options override env.

| Setting | Default | Env | Programmatic | | --- | --- | --- | --- | | HTTP port | 1337 | PORT | startServer({ port }) | | Session idle (ms) | 120000 | SESSION_IDLE_MS | startServer({ sessionIdleMs }) | | Changed debounce (ms) | 125 | CHANGED_DEBOUNCE_MS | startServer({ changedDebounceMs }) | | Qlik config provider | - | - | startServer({ getEnigmaConfig }) | | Qlik connection mode | cloud | QLIK_CONNECTION_MODE | getEnigmaConfig().connectionMode | | Qlik tenant (cloud) | - | QLIK_TENANT | getEnigmaConfig().qlikTenant | | Qlik engine URL (certs) | - | QLIK_ENGINE_URL | getEnigmaConfig().qlikEngineUrl | | Certificates path (certs) | - | QLIK_CERTIFICATES_PATH | getEnigmaConfig().certificatesPath | | Custom session factory | - | - | startServer({ getEnigmaSession }) | | Response interceptors | - | - | startServer({ getResponseInterceptors }) | | Error handler | - | - | startServer({ onError }) | | Logger | console.log | - | startServer({ logger }) |

Notes:

• In cloud mode, clients must provide a Qlik API token (see Client).
• In certificates mode, clients must provide a Qlik user directory.
• Providing getEnigmaConfig bypasses env-based config for Qlik connection settings.
• logger: null disables logs.

Behavior notes

• Sessions are keyed by userId + appId; idle cleanup uses sessionIdleMs.
• If a session is closed or returns NOT_CONNECTED, the gateway marks it dead and rehydrates on the next call or subscription.
• GET /health includes sessionDetails with per-session status (dead/alive, idle time, handles, subscriptions).
• changed can optionally include a layout (see includeLayout in Client options).
• Synthetic loading helps UI state around longer-running calls.
• createSessionObject is cached only when qInfo.qId is provided; cache is per session and cleared by destroySessionObject.

Session lifecycle (short)

• Alive session: enigma session is open; handles point to live APIs; calls go through normally.
• Dead session: enigma session closed or a call returned NOT_CONNECTED; handles are kept but their APIs are cleared.
• Rehydrate: on the next call/subscribe, the gateway opens a new enigma session, recreates global/app, and rebinds known handles (objects/fields/variables/measures). Unknown handles throw SESSION_CLOSED.
• Idle cleanup: a session is disposed only when it has no subscriptions and has been idle longer than sessionIdleMs (same rule for alive and dead).

Client

Usage

import { QlikGatewayClient } from 'claviz-liminal-qlik/client';

const session = await QlikGatewayClient.connectSession('http://localhost:1337', {
  userId: '[email protected]',
  appId: 'YOUR_APP_ID',
  token: process.env.QLIK_API_TOKEN,
  userDirectory: 'YOUR_USER_DIRECTORY', // certificates mode
});

const app = await (await session.open()).openDoc();
const viz = await app.getObject('YOUR_OBJECT_ID');

viz.on('changed', ({ layout }) => {
  // layout is pushed by the server when includeLayout is true
}, { includeLayout: true });

viz.on('loading', ({ active }) => {
  // show/hide overlay
});

await session.close();

Tunable options

• QlikGatewayClient.connect(url, { timeoutMs?, token?, userDirectory? }) (default timeoutMs is 30000).
• QlikGatewayClient.connectSession(url, { userId, appId, timeoutMs?, token?, userDirectory? }).
• openGlobal/openApp params: { userId, appId, token?, userDirectory? } (token used for Qlik Cloud).
• Subscription options: { includeLayout?, debounceMs? } for changed.
• EnigmaGatewaySession.close() only disconnects the socket if it owns it.