@nanolink/nanolink-tools

Toolkit for integrating with the Nanolink infrastructure (core + log servers). Provides:

• High-level Connection class (login, auto‑reconnect, mirror factory, core & log separation)
• Live data mirrors (GraphQL subscription backed) via Mirror (extends MirrorSync from @nanolink/mirrors)
• Simple GraphQL query + subscription helpers (including optional bulk unwind)
• Log server subscription handler

An example integration service shows this package in a real project.

Installation

npm install @nanolink/nanolink-tools

Requires Node >= 20.

Quick Start

import { Connection } from '@nanolink/nanolink-tools';

const conn = new Connection('https://api.nanolink.com/core', process.env.APITOKEN!);

// Optional lifecycle hooks (assign before connect)
conn.onReady = (customer) => {
	console.log('Core ready for', customer.companyName);
};
conn.onMirrorCreated = async (mirror) => {
	// Initialize indices or pre-processing if needed
	console.log('Mirror created:', mirror.name);
};
conn.onDisconnected = () => console.warn('Core disconnected – will auto reconnect');

// Connect (core)
await conn.connect(true); // autoReconnect = true

// Obtain a live mirror (auto updates through GraphQL subscription)
const references = await conn.getMirror('references');
// `references` is a Map-like storage (readonly view). Iterate:
for (const [id, doc] of references) {
	console.log(id, doc);
}

// Run a direct GraphQL query
const result = await conn.query(`query ($id: ID!) { reference(id: $id) { id name } }`, { id: '123' });
console.log(result);

// Subscribe manually (raw subscription)
for await (const evt of await conn.subscribe(`subscription { heartbeat { ts } }`)) {
	console.log('heartbeat', evt.heartbeat);
}

Core Concepts

Connection

Handles:

• Login to core + (optionally) log server
• Auto reconnect logic (configurable)
• Factory for named mirrors (getMirror, releaseMirror)
• Raw GraphQL queries (query) & subscriptions (subscribe / subscribelog)

Mirror

Represents a continuously synchronized, in‑memory projection of a subscription result set.

• Backed by @nanolink/mirrors MirrorSync
• Emits legacy callbacks you can override:
  • onInserted(mirror, doc)
  • onUpdated(mirror, doc, previous)
  • onDeleted(mirror, previous)
• Access current data through mirror.storage (a Map-like structure keyed by entity id)

Log Subscriptions

Use connectLog() then subscribelog() for log server streams (separate WebSocket & token flow).

API Outline

class Connection(url: string, apiToken: string)

Lifecycle Hooks (assignable):

• onReady(customer) – core session established (also after reconnect)
• onDisconnected() / onConnected() – core socket transitions
• onMirrorCreated(mirror) – called before the mirror loads its data (awaitable)
• onLogReady() / onConnectedLog() / onDisconnectedLog() – log server lifecycle

Methods:

• connect(autoReconnect?: boolean)
• connectLog(autoReconnect?: boolean)
• close() / closelog()
• query(query: string, variables?: any)
• subscribe(query: string, variables?: any, unwind?: boolean) – core subscriptions
• subscribelog(query: string, variables?: any, unwind?: boolean) – log subscriptions
• getMirror(name: string) – returns a Map-like storage for a named subscription (defined in internal Subscriptions map)
• getTempMirror(name: string) – ephemeral mirror based on TempSubscriptions
• releaseMirror(name: string) – stop updates & free resources

class Mirror extends MirrorSync

Properties:

• name, query, storage Callbacks (override as needed): onInserted, onUpdated, onDeleted Utility: close() stops internal subscription.

Error Handling

• GraphQL errors inside subscription payloads are surfaced as thrown errors in async iteration.
• Query errors throw the first error object (matching historical behavior).
• Reconnect is delayed (5s) and continues unless close() / closelog() was called.

Development (Contributing)

This repository is authored in TypeScript. Two build modes:

• Production build (excludes test/):

  npm run build

• (If present) a dev build task (build:dev) may include test sources for local debugging (VS Code task / launch config).

Run the VS Code launch configuration "Run test/run.ts" (added in .vscode/launch.json) to execute the local test harness after compiling with the dev tsconfig.

Suggested Workflow

1. Edit sources under src/
2. Build (or use a watch task if added)
3. Use the debug configuration to exercise test scripts in test/
4. Publish with npm run publish (ensures prod build artifacts in lib/)

Legacy Notes

Earlier versions relied on graphql-subscriptions-client and a custom mirror implementation. These have been refactored to leverage @nanolink/mirrors primitives (MirrorSync, SubscriptionClient). Legacy callbacks are preserved for ease of migration.

License

ISC

Support

For access credentials & environment URLs contact Nanolink support.

Changelog (Excerpt)

• 1.0.71 – Refactored to extend MirrorSync & new subscription client; improved dev docs.