FlipID

FlipID is a simple and reversible ID encoder. It transforms numeric IDs into unguessable strings and back.

This is NOT Encryption

FlipID is an ID encoder, not a cryptographic library.

• Does NOT provide security or confidentiality
• Uses Math.sin() based PRNG (predictable, not cryptographically secure)
• Anyone with the key can decode; anyone determined can likely reverse-engineer

Use cases:

• Hiding sequential database IDs in URLs (/users/1 → /users/X7KQ9M)
• Making IDs non-enumerable for casual observers
• URL shorteners, invite codes, etc.

Do NOT use for:

• Protecting sensitive data
• Authentication tokens
• Anything requiring real security

Installation

npm install flipid
# or
bun add flipid

Setup

You need to decide two things:

1. Key

Any string that makes the transformation unique to your application.

• Same key + same input = same output (deterministic)
• Different key = different output
• Keep it consistent across your application
• Store in environment variables or config

2. Block Size

The fixed byte size for encoding. This determines output length.

| blockSize | Max value | Output length | |-----------|--------------------------|---------------| | 1 | 255 (2⁸-1) | 2 chars | | 2 | 65,535 (2¹⁶-1) | 4 chars | | 3 | 16,777,215 (2²⁴-1) | 5 chars | | 4 | ~4 billion (2³²-1) | 7 chars | | 8 | ~18 quintillion (2⁶⁴-1) | 13 chars | | 0 | unlimited (variable) | varies |

• Use blockSize: 4 for typical database IDs (32-bit)
• Use blockSize: 8 for large IDs or UUIDs (64-bit)
• Use blockSize: 0 for variable-length data

Important: Once you choose key and blockSize, keep them unchanged. Changing either will make existing encoded IDs undecodable.

Usage

Basic Example

import { FlipID } from 'flipid';

const flipid = new FlipID({
  key: 'my-app-key',
  blockSize: 4,
});

// Encode a number
const encoded = flipid.encodeNumber(123456);
console.log(encoded); // "59RQ4YPK"

// Decode back to number
const decoded = flipid.decodeToNumber(encoded);
console.log(decoded); // 123456

Encoding Different Types

const flipid = new FlipID({ key: 'my-app-key', blockSize: 8 });

// Numbers
flipid.encodeNumber(42);              // "X32AHV9WN1PHS3"
flipid.decodeToNumber('X32AHV9WN1PHS3'); // 42

// BigInt (for large numbers)
flipid.encodeBigInt(2n ** 64n - 1n);  // "6HRPREKM3HCRTK"
flipid.decodeToBigInt('6HRPREKM3HCRTK'); // 18446744073709551615n

// Strings
flipid.encodeString('hello');         // "1Y0WY29E507G5B9"
flipid.decodeToString('1Y0WY29E507G5B9'); // "hello"

// Buffers
flipid.encodeBuffer(Buffer.from('data')); // "3RY1HMBZZ7CFNZQ"
flipid.decodeToBuffer('3RY1HMBZZ7CFNZQ');  // <Buffer 64 61 74 61>

Custom Encoder

import { FlipID, Codecs } from 'flipid';

// Default: Base32 Crockford (0-9, A-Z excluding I, L, O, U)
const f1 = new FlipID({ key: 'my-app-key', blockSize: 4 });
f1.encodeNumber(1); // "119G0PG1"
f1.encodeNumber(2); // "1C81468G"
f1.encodeNumber(3); // "191562GH"

// Base64 URL-safe (shorter output)
const f2 = new FlipID({ key: 'my-app-key', blockSize: 4, encoder: Codecs.base64url });
f2.encodeNumber(1); // "hTAFoB"
f2.encodeNumber(2); // "sQEhkQ"
f2.encodeNumber(3); // "pCUwoR"

// Base58 (Bitcoin-style, no confusing chars: 0, O, I, l)
const f3 = new FlipID({ key: 'my-app-key', blockSize: 4, encoder: Codecs.base58 });
f3.encodeNumber(1); // "wUJjP6"
f3.encodeNumber(2); // "2FPg1ew"
f3.encodeNumber(3); // "2A8eNmE"

// Hexadecimal
const f4 = new FlipID({ key: 'my-app-key', blockSize: 4, encoder: Codecs.base16 });
f4.encodeNumber(1); // "853005A01"
f4.encodeNumber(2); // "B10121910"
f4.encodeNumber(3); // "A42530A11"

Error Handling

import {
  FlipID,
  FlipIDNumberOverflowError,
  FlipIDInvalidEncodedStringError,
} from 'flipid';

const flipid = new FlipID({ key: 'my-app-key', blockSize: 4 });

try {
  flipid.decodeToBuffer('!!!invalid!!!');
} catch (e) {
  if (e instanceof FlipIDInvalidEncodedStringError) {
    console.error('Invalid encoded string');
  }
}

// For large values, use BigInt methods
const flipid8 = new FlipID({ key: 'my-app-key', blockSize: 8 });
const encoded = flipid8.encodeBigInt(2n ** 60n);
try {
  flipid8.decodeToNumber(encoded); // throws: exceeds MAX_SAFE_INTEGER
} catch (e) {
  if (e instanceof FlipIDNumberOverflowError) {
    const value = flipid8.decodeToBigInt(encoded); // use BigInt instead
  }
}

Signed Integers

FlipID only accepts unsigned integers. Use the utility functions for signed values:

import { FlipID, signedToUnsigned, unsignedToSigned } from 'flipid';

const flipid = new FlipID({ key: 'my-app-key', blockSize: 4 });

// Encode signed integer
const encoded = flipid.encodeNumber(signedToUnsigned(-1));    // 4294967295
const decoded = unsignedToSigned(flipid.decodeToNumber(encoded)); // -1

// For BigInt (64-bit)
import { signedToUnsignedBigInt, unsignedToSignedBigInt } from 'flipid';

const flipid8 = new FlipID({ key: 'my-app-key', blockSize: 8 });
const encoded8 = flipid8.encodeBigInt(signedToUnsignedBigInt(-1n));
const decoded8 = unsignedToSignedBigInt(flipid8.decodeToBigInt(encoded8)); // -1n

API

FlipID

Constructor Options

| Option | Type | Default | Description | |-----------------|-----------|------------------|--------------------------------------------------| | key | string | (required) | Key for encoding/decoding transformation | | blockSize | number | 4 | Fixed block size in bytes. 0 = variable length | | headerSize | number | 1 | Bytes for internal IV (1-4). Larger = more variation | | checkSum | boolean | false | Enable checksum validation on decode | | usePrefixSalt | boolean | false | Add single-char prefix salt to output | | encoder | ICodec | Base32Crockford | Custom encoder from bufferbase |

Methods

Encoding:

• encode(data, prefixSalt?) - Polymorphic encoding (number, bigint, string, or Buffer)
• encodeNumber(num, prefixSalt?) - Encode number or bigint
• encodeBigInt(num, prefixSalt?) - Encode bigint (type-safe)
• encodeString(str, prefixSalt?) - Encode string
• encodeBuffer(buffer, prefixSalt?) - Encode buffer

Decoding:

• decodeToNumber(encoded) - Decode to number (throws if > MAX_SAFE_INTEGER)
• decodeToBigInt(encoded) - Decode to bigint
• decodeToString(encoded) - Decode to string
• decodeToBuffer(encoded) - Decode to buffer

Error Classes

| Error | Description | |-----------------------------------|------------------------------------------------| | FlipIDInvalidDataTypeError | Invalid input data type | | FlipIDBlockTooLargeError | Input exceeds configured blockSize | | FlipIDInvalidArgumentError | Invalid argument combination | | FlipIDChecksumError | Checksum mismatch on decode | | FlipIDNumberOverflowError | Decoded value exceeds Number.MAX_SAFE_INTEGER | | FlipIDInvalidEncodedStringError | Invalid encoded string format |

License

ISC