@signal-js/core

Core utilities and shared functionality for Signal SDK.

Installation

``bash
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

$3

`typescript
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);
`

$3

`typescript
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' });
`

$3

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

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

$3

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

const uuid = uuidv7(); // Time-sortable UUID
const sessionId = generateSessionId(); // s__

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

$3

`typescript
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

$3

| 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 |

$3

| 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 |

$3

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

$3

| 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