@tabsircg/snowflake 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export type SnowflakeId<T extends boolean> = T extends true ? string : bigint;
+/**
+ * Creates a Snowflake ID generator with consistent sequence tracking.
+ *
+ * @param workerId - Unique worker identifier
+ * @param datacenterId - Unique datacenter identifier
+ * @returns Function that generates unique Snowflake IDs
+ *
+ * @example
+ * const generator = createSnowflakeGenerator(1, 1);
+ * const id = generator(); // 1234567890123456789n
+ * const stringId = generator(true); // "1234567890123456789"
+ */
+export declare const createSnowflakeGenerator: (workerId: number, datacenterId: number) => <T extends boolean = false>(returnAsString?: T) => SnowflakeId<T>;
+/**
+ * Generates a Snowflake ID for a specific timestamp (used for cleanup thresholds).
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @param workerId - Worker ID (default: 0 for minimum possible ID)
+ * @param datacenterId - Datacenter ID (default: 0 for minimum possible ID)
+ * @param sequence - Sequence number (default: 0 for minimum possible ID)
+ * @returns Snowflake ID as BigInt
+ *
+ * @example
+ * // Get threshold for deleting records older than 30 days
+ * const thirtyDaysAgo = Date.now() - (30 * 24 * 60 * 60 * 1000);
+ * const threshold = generateTimestampSnowflake(thirtyDaysAgo);
+ */
+export declare const generateTimestampSnowflake: (timestamp: number, workerId: number, datacenterId: number, sequence: number) => bigint;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,IAAI,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9E;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,wBAAwB,GACnC,UAAU,MAAM,EAChB,cAAc,MAAM,MAyBZ,CAAC,SAAS,OAAO,GAAG,KAAK,EAAE,iBAAiB,CAAC,KAAG,WAAW,CAAC,CAAC,CA+BtE,CAAC;AAEF;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,0BAA0B,GACrC,WAAW,MAAM,EACjB,UAAU,MAAM,EAChB,cAAc,MAAM,EACpB,UAAU,MAAM,WAUjB,CAAC"}

package/dist/index.js

@@ -0,0 +1,93 @@
+const SNOWFLAKE_EPOCH = 1770479980106;
+const SNOWFLAKE_BITS = {
+    SEQUENCE: 11,
+    WORKER_ID: 4,
+    DATACENTER_ID: 5,
+};
+const SNOWFLAKE_SHIFTS = {
+    WORKER_ID: SNOWFLAKE_BITS.SEQUENCE,
+    DATACENTER_ID: SNOWFLAKE_BITS.SEQUENCE + SNOWFLAKE_BITS.WORKER_ID,
+    TIMESTAMP: SNOWFLAKE_BITS.SEQUENCE +
+        SNOWFLAKE_BITS.WORKER_ID +
+        SNOWFLAKE_BITS.DATACENTER_ID,
+};
+const SNOWFLAKE_MASKS = {
+    SEQUENCE: (1 << SNOWFLAKE_BITS.SEQUENCE) - 1,
+};
+/**
+ * Creates a Snowflake ID generator with consistent sequence tracking.
+ *
+ * @param workerId - Unique worker identifier
+ * @param datacenterId - Unique datacenter identifier
+ * @returns Function that generates unique Snowflake IDs
+ *
+ * @example
+ * const generator = createSnowflakeGenerator(1, 1);
+ * const id = generator(); // 1234567890123456789n
+ * const stringId = generator(true); // "1234567890123456789"
+ */
+export const createSnowflakeGenerator = (workerId, datacenterId) => {
+    const maxWorkerId = (1 << SNOWFLAKE_BITS.WORKER_ID) - 1;
+    const maxDatacenterId = (1 << SNOWFLAKE_BITS.DATACENTER_ID) - 1;
+    if (workerId < 0 || workerId > maxWorkerId) {
+        throw new Error(`Worker ID must be between 0 and ${maxWorkerId}`);
+    }
+    if (datacenterId < 0 || datacenterId > maxDatacenterId) {
+        throw new Error(`Datacenter ID must be between 0 and ${maxDatacenterId}`);
+    }
+    let sequence = 0;
+    let lastTimestamp = -1;
+    const getCurrentTimestamp = () => Date.now();
+    const waitForNextMillis = (lastTimestamp) => {
+        let timestamp = getCurrentTimestamp();
+        while (timestamp <= lastTimestamp) {
+            timestamp = getCurrentTimestamp();
+        }
+        return timestamp;
+    };
+    return (returnAsString) => {
+        let timestamp = getCurrentTimestamp();
+        if (timestamp < lastTimestamp) {
+            throw new Error(`Clock moved backwards. Refusing to generate id for ${lastTimestamp - timestamp} milliseconds`);
+        }
+        if (timestamp === lastTimestamp) {
+            sequence = (sequence + 1) & SNOWFLAKE_MASKS.SEQUENCE;
+            if (sequence === 0) {
+                timestamp = waitForNextMillis(lastTimestamp);
+            }
+        }
+        else {
+            sequence = 0;
+        }
+        lastTimestamp = timestamp;
+        const id = (BigInt(timestamp - SNOWFLAKE_EPOCH) <<
+            BigInt(SNOWFLAKE_SHIFTS.TIMESTAMP)) +
+            (BigInt(datacenterId) << BigInt(SNOWFLAKE_SHIFTS.DATACENTER_ID)) +
+            (BigInt(workerId) << BigInt(SNOWFLAKE_SHIFTS.WORKER_ID)) +
+            BigInt(sequence);
+        return (returnAsString ? id.toString() : id);
+    };
+};
+/**
+ * Generates a Snowflake ID for a specific timestamp (used for cleanup thresholds).
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @param workerId - Worker ID (default: 0 for minimum possible ID)
+ * @param datacenterId - Datacenter ID (default: 0 for minimum possible ID)
+ * @param sequence - Sequence number (default: 0 for minimum possible ID)
+ * @returns Snowflake ID as BigInt
+ *
+ * @example
+ * // Get threshold for deleting records older than 30 days
+ * const thirtyDaysAgo = Date.now() - (30 * 24 * 60 * 60 * 1000);
+ * const threshold = generateTimestampSnowflake(thirtyDaysAgo);
+ */
+export const generateTimestampSnowflake = (timestamp, workerId, datacenterId, sequence) => {
+    const id = (BigInt(timestamp - SNOWFLAKE_EPOCH) <<
+        BigInt(SNOWFLAKE_SHIFTS.TIMESTAMP)) +
+        (BigInt(datacenterId) << BigInt(SNOWFLAKE_SHIFTS.DATACENTER_ID)) +
+        (BigInt(workerId) << BigInt(SNOWFLAKE_SHIFTS.WORKER_ID)) +
+        BigInt(sequence);
+    return id;
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tabsircg/snowflake",
+  "version": "1.0.0",
+  "description": "Lightweight Snowflake ID generator for Node.js",
+  "license": "ISC",
+  "author": "Tabsir CG",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "snowflake",
+    "id",
+    "generator",
+    "distributed",
+    "unique-id"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}