@dreamystify/fingrprint v1.0.1

Getting started

Prerequisites

• Node.js v18+
• Redis v7+ (or a Redis Cluster for distributed mode)

# Initialize the repo (if applicable)
./.scripts/init.sh

Installation

npm install @dreamystify/fingrprint

To build the package locally with the TypeScript compiler, run:

npm run build

Usage

The Fingrprint library supports three connection modes: standalone, Sentinel, and Cluster. Below are examples for each mode.

Standalone Mode

import { Fingrprint } from '@dreamystify/fingrprint';

(async () => {
  // Initialize Fingrprint with standalone Redis
  const fingrprint = await Fingrprint.initialize({
    host: 'localhost',
    port: 6379,
    username: 'yourUsername',    // if using authentication
    password: 'yourPassword',    // if using authentication
    database: 0,
  });

  // Generate a single unique ID
  const id = await fingrprint.getId();
  console.log('Generated ID:', id);
  
  // Generate a batch of 3 IDs
  const ids = await fingrprint.getIds(3);
  console.log('Generated IDs:', ids);
})();

Sentinel Mode

import { Fingrprint } from '@dreamystify/fingrprint';

(async () => {
  // Initialize Fingrprint using Redis Sentinel
  const fingrprint = await Fingrprint.initialize({
    sentinels: [
      { host: 'sentinel1', port: 26379 },
      { host: 'sentinel2', port: 26379 }
    ],
    name: 'mymaster',             // name of your master instance
    username: 'yourUsername',     // for the master
    password: 'yourPassword',     // for the master
    sentinelUsername: 'sentinelUser',    // if your Sentinel requires authentication
    sentinelPassword: 'sentinelPassword',// if your Sentinel requires authentication
    database: 0,
  });

  const id = await fingrprint.getId();
  console.log('Generated ID:', id);
})();

Cluster Mode

import { Fingrprint } from '@dreamystify/fingrprint';

(async () => {
  // Initialize Fingrprint using Redis Cluster
  const fingrprint = await Fingrprint.initialize({
    clusterNodes: [
      { host: 'redis-cluster-node1', port: 6379 },
      { host: 'redis-cluster-node2', port: 6379 },
      { host: 'redis-cluster-node3', port: 6379 }
    ],
    username: 'yourUsername',   // for cluster authentication
    password: 'yourPassword',   // for cluster authentication
    database: 0,
  });

  const id = await fingrprint.getId();
  console.log('Generated ID:', id);
})();

Sharding Configuration

import { Fingrprint } from '@dreamystify/fingrprint';

(async () => {
  // Initialize Fingrprint with a custom shard configuration (for standalone mode)
  const fingrprint = await Fingrprint.initialize({
    host: 'localhost',
    port: 6379,
    username: 'yourUsername',
    password: 'yourPassword',
    database: 0,
    // Optionally set a fixed shard ID via environment variable:
    // FINGRPRINT_SHARD_ID_KEY: '{fingrprint}-shard-id',
    // FINGRPRINT_SHARD_ID: '1',
  });

  const id = await fingrprint.getId();
  console.log('Generated ID:', id);
})();

In Cluster mode, the library automatically assigns shard IDs to master nodes based on the cluster topology. You can later query each node (using redis-cli) to see the assigned shard IDs:

docker run -it --rm --network redis_cluster redis:7.0.2 redis-cli -a yourPassword --cluster call redis-cluster-node1:6379 GET '{fingrprint}-shard-id'

Error Handling

Fingrprint emits events for errors. It is designed to let your application handle logging and error processing in a way that suits your needs. For example:

fingrprint.on('error', (error) => {
  console.error('Fingrprint error:', error.error);
});

fingrprint.on('connect', () => {
  console.log('Fingrprint connected to Redis');
});

Events

Testing

# Start the testing environment
ahoy start

# Run the tests 
npm test

# Stop the testing environment
ahoy stop

Testing Sentinel and Cluster

# Start the testing environment
ahoy start

# Check docker logs 
ahoy logs

# Stop the testing environment
ahoy stop

Kudos

The project was inspired by Icicle, just setup for node.js.