@signal-js/core

Core utilities and shared functionality for Signal SDK.

Installation

npm install @signal-js/core
# or
pnpm add @signal-js/core
# or
yarn add @signal-js/core

Features

• Environment Detection: Safe browser/Node.js detection
• Storage Layer: Cookie, localStorage, sessionStorage with fallback chain
• Session Management: Configurable timeouts, UUIDv7, activity tracking
• Compression: Gzip compression using fflate
• Logger: Debug-aware logging with scoped loggers
• Utilities: Type checking, string manipulation, async helpers

Usage

Session Management

import { createSessionManager, SessionIdManager } from '@signal-js/core';

const session = createSessionManager({
  sessionIdleTimeoutSeconds: 30 * 60, // 30 minutes
  maxSessionLengthSeconds: 24 * 60 * 60, // 24 hours
});

// Get session ID (creates new one if expired)
const sessionId = session.getSessionId();

// Listen for session changes
session.onSessionId((sessionId, windowId, reason) => {
  console.log('Session changed:', sessionId, reason);
});

// Bootstrap with existing session
session.bootstrap(existingSessionId);

Storage

import { StorageWrapper, localStore, cookieStore, hybridStore } from '@signal-js/core';

// Use wrapper with prefix
const storage = new StorageWrapper('local', 'myapp');
storage.setJSON('user', { name: 'John' });
const user = storage.getJSON('user');

// Use cookie store directly
cookieStore._set('session_id', 'abc123', 365, true, true);

// Hybrid store (localStorage + cookie for critical data)
hybridStore._set('data', { session_id: 'abc', other: 'value' });

Compression

import { gzipCompress, isGzipSupported } from '@signal-js/core';

if (isGzipSupported()) {
  const compressed = gzipCompress(JSON.stringify(data));
  // Send with Content-Encoding: gzip
}

UUID Generation

import { uuidv7, generateSessionId, uuid7ToTimestampMs } from '@signal-js/core';

const uuid = uuidv7(); // Time-sortable UUID
const sessionId = generateSessionId(); // s_<timestamp>_<random>

// Extract timestamp from UUIDv7
const timestamp = uuid7ToTimestampMs(uuid);

Logging

import { createLogger, setDebug } from '@signal-js/core';

setDebug(true); // Enable debug logging

const logger = createLogger('[MyComponent]');
logger.info('Something happened');
logger.error('Error occurred', error);

API Reference

Environment

| Function | Description | |----------|-------------| | isBrowser() | Check if running in browser | | isNode() | Check if running in Node.js | | hasDocument() | Check if document is available | | hasLocalStorage() | Check if localStorage works | | now() | Current timestamp in ms | | isoTimestamp() | Current ISO timestamp string |

Storage

| Export | Description | |--------|-------------| | localStore | localStorage wrapper | | sessionStore | sessionStorage wrapper | | cookieStore | Cookie store with subdomain support | | memoryStore | In-memory fallback store | | hybridStore | localStorage + cookie for critical keys | | StorageWrapper | Class with prefix support |

Session

| Export | Description | |--------|-------------| | SessionIdManager | Full session management class | | createSessionManager() | Factory function |

Utilities

| Function | Description | |----------|-------------| | safeStringify() | JSON stringify with circular reference handling | | redactSensitiveData() | Redact passwords, tokens, etc. | | truncate() | Truncate strings with suffix | | retriable() | Retry async operations | | clampToRange() | Clamp numbers to range |

License

MIT