@toolkit-f/snowflake-id 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MAULIK MK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var m=1023,c=4095n,i=12n,o=22n,s=17040672e5;var a=class{constructor(e){this.sequence=0n;this.lastTimestamp=-1;let{machineId:n,epoch:r=17040672e5,clockMoveBackAction:f="throw"}=e;if(n<0||n>1023||!Number.isInteger(n))throw new Error(`machineId must be integer 0-1023, got ${n}`);if(r<0||r>Date.now())throw new Error("epoch cannot be in the future");this.machineIdShifted=BigInt(n)<<i,this.epoch=r,this.clockMoveBackAction=f;}nextId(){let e=Date.now();if(e<this.lastTimestamp){let n=this.lastTimestamp-e;if(this.clockMoveBackAction==="wait"&&n<=50)for(;e<=this.lastTimestamp;)e=Date.now();else throw new Error(`Clock moved backwards by ${n}ms`)}if(e===this.lastTimestamp){if(this.sequence=this.sequence+1n&c,this.sequence===0n)for(;e<=this.lastTimestamp;)e=Date.now();}else this.sequence=0n;return this.lastTimestamp=e,BigInt(e-this.epoch)<<o|this.machineIdShifted|this.sequence}nextIdString(){return this.nextId().toString()}getMachineId(){return Number(this.machineIdShifted>>i)}getEpoch(){return this.epoch}getSequence(){return Number(this.sequence)}getLastTimestamp(){return this.lastTimestamp}};function p(t){return new a(t)}var g=c,u=BigInt(1023);function I(t,e=17040672e5){if(typeof t=="string"&&!/^\d+$/.test(t))throw new Error(`Invalid Snowflake ID: "${t}"`);let n=typeof t=="string"?BigInt(t):t,r=Number(n>>o)+e;return {id:n,timestamp:new Date(r),timestampMs:r,machineId:Number(n>>i&u),sequence:Number(n&g)}}function l(t){return {id:t.id.toString(),timestamp:t.timestamp.toISOString(),timestampMs:t.timestampMs,machineId:t.machineId,sequence:t.sequence}}function S(t,e=17040672e5){let n=typeof t=="string"?BigInt(t):t;return new Date(Number(n>>o)+e)}function h(t){let e=typeof t=="string"?BigInt(t):t;return Number(e>>i&u)}function w(t){let e=typeof t=="string"?BigInt(t):t;return Number(e&g)}function k(t,e=17040672e5,n=false){if(typeof t=="string"){if(!/^\d+$/.test(t))return  false;try{t=BigInt(t);}catch{return  false}}if(typeof t!="bigint"||t<0n)return  false;if(n)return  true;let r=Number(t>>o)+e;return r>=e&&r<=Date.now()+1e3}function E(t){return t.toString()}function M(t){if(!/^\d+$/.test(t))throw new Error(`Invalid Snowflake ID string: "${t}"`);return BigInt(t)}function T(t,e){let n=typeof t=="string"?BigInt(t):t,r=typeof e=="string"?BigInt(e):e;return n<r?-1:n>r?1:0}function b(t,e=0,n=0,r=17040672e5){let f=typeof t=="number"?t:t.getTime();return BigInt(f-r)<<o|BigInt(e)<<i|BigInt(n)}exports.DEFAULT_EPOCH=s;exports.MACHINE_ID_SHIFT=i;exports.MAX_MACHINE_ID=m;exports.MAX_SEQUENCE=c;exports.SnowflakeGenerator=a;exports.TIMESTAMP_SHIFT=o;exports.compareSnowflakes=T;exports.createGenerator=p;exports.getMachineId=h;exports.getSequence=w;exports.getTimestamp=S;exports.isValidSnowflake=k;exports.parseSnowflake=I;exports.snowflakeFromTimestamp=b;exports.snowflakeToString=E;exports.stringToSnowflake=M;exports.stringifySnowflakeParts=l;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/generator.ts","../src/utils/index.ts"],"names":["MAX_MACHINE_ID","MAX_SEQUENCE","MACHINE_ID_SHIFT","TIMESTAMP_SHIFT","DEFAULT_EPOCH","SnowflakeGenerator","config","machineId","epoch","clockMoveBackAction","ts","drift","createGenerator","SEQUENCE_MASK","MACHINE_ID_MASK","parseSnowflake","id","sfId","timestampMs","stringifySnowflakeParts","parts","getTimestamp","getMachineId","getSequence","isValidSnowflake","relaxed","snowflakeToString","stringToSnowflake","str","compareSnowflakes","a","b","idA","idB","snowflakeFromTimestamp","date","sequence"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { SnowflakeConfig } from '../types/type';\n\nconst MAX_MACHINE_ID = 1023;\nconst MAX_SEQUENCE = 4095n;\nconst MACHINE_ID_SHIFT = 12n;\nconst TIMESTAMP_SHIFT = 22n;\nconst DEFAULT_EPOCH = 1704067200000;\nconst MAX_CLOCK_WAIT_MS = 50;\n\n/**\n * Generates 64-bit, time-sortable unique IDs.\n */\nexport class SnowflakeGenerator {\n    private readonly machineIdShifted: bigint;\n    private readonly epoch: number;\n    private readonly clockMoveBackAction: 'throw' | 'wait';\n    private sequence = 0n;\n    private lastTimestamp = -1;\n\n    constructor(config: SnowflakeConfig) {\n        const { machineId, epoch = DEFAULT_EPOCH, clockMoveBackAction = 'throw' } = config;\n\n        if (machineId < 0 || machineId > MAX_MACHINE_ID || !Number.isInteger(machineId)) {\n            throw new Error(`machineId must be integer 0-1023, got ${machineId}`);\n        }\n\n        if (epoch < 0 || epoch > Date.now()) {\n            throw new Error(`epoch cannot be in the future`);\n        }\n\n        this.machineIdShifted = BigInt(machineId) << MACHINE_ID_SHIFT;\n        this.epoch = epoch;\n        this.clockMoveBackAction = clockMoveBackAction;\n    }\n\n    /**\n     * @throws Error if the system clock drifts backwards.\n     */\n    nextId(): bigint {\n        let ts = Date.now();\n\n        if (ts < this.lastTimestamp) {\n            const drift = this.lastTimestamp - ts;\n\n            if (this.clockMoveBackAction === 'wait' && drift <= MAX_CLOCK_WAIT_MS) {\n                while (ts <= this.lastTimestamp) {\n                    ts = Date.now();\n                }\n            } else {\n                throw new Error(`Clock moved backwards by ${drift}ms`);\n            }\n        }\n\n        if (ts === this.lastTimestamp) {\n            this.sequence = (this.sequence + 1n) & MAX_SEQUENCE;\n            if (this.sequence === 0n) {\n                while (ts <= this.lastTimestamp) {\n                    ts = Date.now();\n                }\n            }\n        } else {\n            this.sequence = 0n;\n        }\n\n        this.lastTimestamp = ts;\n        return (BigInt(ts - this.epoch) << TIMESTAMP_SHIFT) | this.machineIdShifted | this.sequence;\n    }\n\n    nextIdString(): string {\n        return this.nextId().toString();\n    }\n\n    getMachineId(): number {\n        return Number(this.machineIdShifted >> MACHINE_ID_SHIFT);\n    }\n\n    getEpoch(): number {\n        return this.epoch;\n    }\n\n    getSequence(): number {\n        return Number(this.sequence);\n    }\n\n    getLastTimestamp(): number {\n        return this.lastTimestamp;\n    }\n}\n\nexport function createGenerator(config: SnowflakeConfig): SnowflakeGenerator {\n    return new SnowflakeGenerator(config);\n}\n\nexport {\n    MAX_SEQUENCE,\n    MACHINE_ID_SHIFT,\n    TIMESTAMP_SHIFT,\n    DEFAULT_EPOCH,\n    MAX_MACHINE_ID,\n};","import type { SnowflakeParts, SnowflakePartsJSON } from '../types/type';\nimport {\n    MACHINE_ID_SHIFT,\n    TIMESTAMP_SHIFT,\n    DEFAULT_EPOCH,\n    MAX_SEQUENCE,\n    MAX_MACHINE_ID\n} from '../core/generator';\n\nconst SEQUENCE_MASK = MAX_SEQUENCE;\nconst MACHINE_ID_MASK = BigInt(MAX_MACHINE_ID);\n\nexport function parseSnowflake(id: bigint | string, epoch = DEFAULT_EPOCH): SnowflakeParts {\n    if (typeof id === 'string' && !/^\\d+$/.test(id)) {\n        throw new Error(`Invalid Snowflake ID: \"${id}\"`);\n    }\n\n    const sfId = typeof id === 'string' ? BigInt(id) : id;\n    const timestampMs = Number(sfId >> TIMESTAMP_SHIFT) + epoch;\n\n    return {\n        id: sfId,\n        timestamp: new Date(timestampMs),\n        timestampMs,\n        machineId: Number((sfId >> MACHINE_ID_SHIFT) & MACHINE_ID_MASK),\n        sequence: Number(sfId & SEQUENCE_MASK),\n    };\n}\n\nexport function stringifySnowflakeParts(parts: SnowflakeParts): SnowflakePartsJSON {\n    return {\n        id: parts.id.toString(),\n        timestamp: parts.timestamp.toISOString(),\n        timestampMs: parts.timestampMs,\n        machineId: parts.machineId,\n        sequence: parts.sequence,\n    };\n}\n\nexport function getTimestamp(id: bigint | string, epoch = DEFAULT_EPOCH): Date {\n    const sfId = typeof id === 'string' ? BigInt(id) : id;\n    return new Date(Number(sfId >> TIMESTAMP_SHIFT) + epoch);\n}\n\nexport function getMachineId(id: bigint | string): number {\n    const sfId = typeof id === 'string' ? BigInt(id) : id;\n    return Number((sfId >> MACHINE_ID_SHIFT) & MACHINE_ID_MASK);\n}\n\nexport function getSequence(id: bigint | string): number {\n    const sfId = typeof id === 'string' ? BigInt(id) : id;\n    return Number(sfId & SEQUENCE_MASK);\n}\n\n/**\n * @param relaxed - Skip timestamp range check.\n */\nexport function isValidSnowflake(id: unknown, epoch = DEFAULT_EPOCH, relaxed = false): boolean {\n    if (typeof id === 'string') {\n        if (!/^\\d+$/.test(id)) return false;\n        try {\n            id = BigInt(id);\n        } catch {\n            return false;\n        }\n    }\n\n    if (typeof id !== 'bigint' || id < 0n) return false;\n    if (relaxed) return true;\n\n    const ts = Number(id >> TIMESTAMP_SHIFT) + epoch;\n    return ts >= epoch && ts <= Date.now() + 1000;\n}\n\nexport function snowflakeToString(id: bigint): string {\n    return id.toString();\n}\n\nexport function stringToSnowflake(str: string): bigint {\n    if (!/^\\d+$/.test(str)) {\n        throw new Error(`Invalid Snowflake ID string: \"${str}\"`);\n    }\n    return BigInt(str);\n}\n\nexport function compareSnowflakes(a: bigint | string, b: bigint | string): -1 | 0 | 1 {\n    const idA = typeof a === 'string' ? BigInt(a) : a;\n    const idB = typeof b === 'string' ? BigInt(b) : b;\n    return idA < idB ? -1 : idA > idB ? 1 : 0;\n}\n\nexport function snowflakeFromTimestamp(\n    date: Date | number,\n    machineId = 0,\n    sequence = 0,\n    epoch = DEFAULT_EPOCH\n): bigint {\n    const ts = typeof date === 'number' ? date : date.getTime();\n    return (BigInt(ts - epoch) << TIMESTAMP_SHIFT) | (BigInt(machineId) << MACHINE_ID_SHIFT) | BigInt(sequence);\n}"]}

package/dist/index.d.cts

@@ -0,0 +1,65 @@
+interface SnowflakeConfig {
+    /** Unique ID for this machine/worker (0-1023). */
+    machineId: number;
+    /** Custom epoch (milliseconds). Defaults to Jan 1, 2024. */
+    epoch?: number;
+    /** Behavior when system clock drifts backwards. */
+    clockMoveBackAction?: 'throw' | 'wait';
+}
+interface SnowflakeParts {
+    id: bigint;
+    timestamp: Date;
+    timestampMs: number;
+    machineId: number;
+    sequence: number;
+}
+interface SnowflakePartsJSON {
+    id: string;
+    timestamp: string;
+    timestampMs: number;
+    machineId: number;
+    sequence: number;
+}
+
+declare const MAX_MACHINE_ID = 1023;
+declare const MAX_SEQUENCE = 4095n;
+declare const MACHINE_ID_SHIFT = 12n;
+declare const TIMESTAMP_SHIFT = 22n;
+declare const DEFAULT_EPOCH = 1704067200000;
+/**
+ * Generates 64-bit, time-sortable unique IDs.
+ */
+declare class SnowflakeGenerator {
+    private readonly machineIdShifted;
+    private readonly epoch;
+    private readonly clockMoveBackAction;
+    private sequence;
+    private lastTimestamp;
+    constructor(config: SnowflakeConfig);
+    /**
+     * @throws Error if the system clock drifts backwards.
+     */
+    nextId(): bigint;
+    nextIdString(): string;
+    getMachineId(): number;
+    getEpoch(): number;
+    getSequence(): number;
+    getLastTimestamp(): number;
+}
+declare function createGenerator(config: SnowflakeConfig): SnowflakeGenerator;
+
+declare function parseSnowflake(id: bigint | string, epoch?: number): SnowflakeParts;
+declare function stringifySnowflakeParts(parts: SnowflakeParts): SnowflakePartsJSON;
+declare function getTimestamp(id: bigint | string, epoch?: number): Date;
+declare function getMachineId(id: bigint | string): number;
+declare function getSequence(id: bigint | string): number;
+/**
+ * @param relaxed - Skip timestamp range check.
+ */
+declare function isValidSnowflake(id: unknown, epoch?: number, relaxed?: boolean): boolean;
+declare function snowflakeToString(id: bigint): string;
+declare function stringToSnowflake(str: string): bigint;
+declare function compareSnowflakes(a: bigint | string, b: bigint | string): -1 | 0 | 1;
+declare function snowflakeFromTimestamp(date: Date | number, machineId?: number, sequence?: number, epoch?: number): bigint;
+
+export { DEFAULT_EPOCH, MACHINE_ID_SHIFT, MAX_MACHINE_ID, MAX_SEQUENCE, type SnowflakeConfig, SnowflakeGenerator, type SnowflakeParts, type SnowflakePartsJSON, TIMESTAMP_SHIFT, compareSnowflakes, createGenerator, getMachineId, getSequence, getTimestamp, isValidSnowflake, parseSnowflake, snowflakeFromTimestamp, snowflakeToString, stringToSnowflake, stringifySnowflakeParts };

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+interface SnowflakeConfig {
+    /** Unique ID for this machine/worker (0-1023). */
+    machineId: number;
+    /** Custom epoch (milliseconds). Defaults to Jan 1, 2024. */
+    epoch?: number;
+    /** Behavior when system clock drifts backwards. */
+    clockMoveBackAction?: 'throw' | 'wait';
+}
+interface SnowflakeParts {
+    id: bigint;
+    timestamp: Date;
+    timestampMs: number;
+    machineId: number;
+    sequence: number;
+}
+interface SnowflakePartsJSON {
+    id: string;
+    timestamp: string;
+    timestampMs: number;
+    machineId: number;
+    sequence: number;
+}
+
+declare const MAX_MACHINE_ID = 1023;
+declare const MAX_SEQUENCE = 4095n;
+declare const MACHINE_ID_SHIFT = 12n;
+declare const TIMESTAMP_SHIFT = 22n;
+declare const DEFAULT_EPOCH = 1704067200000;
+/**
+ * Generates 64-bit, time-sortable unique IDs.
+ */
+declare class SnowflakeGenerator {
+    private readonly machineIdShifted;
+    private readonly epoch;
+    private readonly clockMoveBackAction;
+    private sequence;
+    private lastTimestamp;
+    constructor(config: SnowflakeConfig);
+    /**
+     * @throws Error if the system clock drifts backwards.
+     */
+    nextId(): bigint;
+    nextIdString(): string;
+    getMachineId(): number;
+    getEpoch(): number;
+    getSequence(): number;
+    getLastTimestamp(): number;
+}
+declare function createGenerator(config: SnowflakeConfig): SnowflakeGenerator;
+
+declare function parseSnowflake(id: bigint | string, epoch?: number): SnowflakeParts;
+declare function stringifySnowflakeParts(parts: SnowflakeParts): SnowflakePartsJSON;
+declare function getTimestamp(id: bigint | string, epoch?: number): Date;
+declare function getMachineId(id: bigint | string): number;
+declare function getSequence(id: bigint | string): number;
+/**
+ * @param relaxed - Skip timestamp range check.
+ */
+declare function isValidSnowflake(id: unknown, epoch?: number, relaxed?: boolean): boolean;
+declare function snowflakeToString(id: bigint): string;
+declare function stringToSnowflake(str: string): bigint;
+declare function compareSnowflakes(a: bigint | string, b: bigint | string): -1 | 0 | 1;
+declare function snowflakeFromTimestamp(date: Date | number, machineId?: number, sequence?: number, epoch?: number): bigint;
+
+export { DEFAULT_EPOCH, MACHINE_ID_SHIFT, MAX_MACHINE_ID, MAX_SEQUENCE, type SnowflakeConfig, SnowflakeGenerator, type SnowflakeParts, type SnowflakePartsJSON, TIMESTAMP_SHIFT, compareSnowflakes, createGenerator, getMachineId, getSequence, getTimestamp, isValidSnowflake, parseSnowflake, snowflakeFromTimestamp, snowflakeToString, stringToSnowflake, stringifySnowflakeParts };

package/dist/index.js

@@ -0,0 +1,2 @@
+var m=1023,c=4095n,i=12n,o=22n,s=17040672e5;var a=class{constructor(e){this.sequence=0n;this.lastTimestamp=-1;let{machineId:n,epoch:r=17040672e5,clockMoveBackAction:f="throw"}=e;if(n<0||n>1023||!Number.isInteger(n))throw new Error(`machineId must be integer 0-1023, got ${n}`);if(r<0||r>Date.now())throw new Error("epoch cannot be in the future");this.machineIdShifted=BigInt(n)<<i,this.epoch=r,this.clockMoveBackAction=f;}nextId(){let e=Date.now();if(e<this.lastTimestamp){let n=this.lastTimestamp-e;if(this.clockMoveBackAction==="wait"&&n<=50)for(;e<=this.lastTimestamp;)e=Date.now();else throw new Error(`Clock moved backwards by ${n}ms`)}if(e===this.lastTimestamp){if(this.sequence=this.sequence+1n&c,this.sequence===0n)for(;e<=this.lastTimestamp;)e=Date.now();}else this.sequence=0n;return this.lastTimestamp=e,BigInt(e-this.epoch)<<o|this.machineIdShifted|this.sequence}nextIdString(){return this.nextId().toString()}getMachineId(){return Number(this.machineIdShifted>>i)}getEpoch(){return this.epoch}getSequence(){return Number(this.sequence)}getLastTimestamp(){return this.lastTimestamp}};function p(t){return new a(t)}var g=c,u=BigInt(1023);function I(t,e=17040672e5){if(typeof t=="string"&&!/^\d+$/.test(t))throw new Error(`Invalid Snowflake ID: "${t}"`);let n=typeof t=="string"?BigInt(t):t,r=Number(n>>o)+e;return {id:n,timestamp:new Date(r),timestampMs:r,machineId:Number(n>>i&u),sequence:Number(n&g)}}function l(t){return {id:t.id.toString(),timestamp:t.timestamp.toISOString(),timestampMs:t.timestampMs,machineId:t.machineId,sequence:t.sequence}}function S(t,e=17040672e5){let n=typeof t=="string"?BigInt(t):t;return new Date(Number(n>>o)+e)}function h(t){let e=typeof t=="string"?BigInt(t):t;return Number(e>>i&u)}function w(t){let e=typeof t=="string"?BigInt(t):t;return Number(e&g)}function k(t,e=17040672e5,n=false){if(typeof t=="string"){if(!/^\d+$/.test(t))return  false;try{t=BigInt(t);}catch{return  false}}if(typeof t!="bigint"||t<0n)return  false;if(n)return  true;let r=Number(t>>o)+e;return r>=e&&r<=Date.now()+1e3}function E(t){return t.toString()}function M(t){if(!/^\d+$/.test(t))throw new Error(`Invalid Snowflake ID string: "${t}"`);return BigInt(t)}function T(t,e){let n=typeof t=="string"?BigInt(t):t,r=typeof e=="string"?BigInt(e):e;return n<r?-1:n>r?1:0}function b(t,e=0,n=0,r=17040672e5){let f=typeof t=="number"?t:t.getTime();return BigInt(f-r)<<o|BigInt(e)<<i|BigInt(n)}export{s as DEFAULT_EPOCH,i as MACHINE_ID_SHIFT,m as MAX_MACHINE_ID,c as MAX_SEQUENCE,a as SnowflakeGenerator,o as TIMESTAMP_SHIFT,T as compareSnowflakes,p as createGenerator,h as getMachineId,w as getSequence,S as getTimestamp,k as isValidSnowflake,I as parseSnowflake,b as snowflakeFromTimestamp,E as snowflakeToString,M as stringToSnowflake,l as stringifySnowflakeParts};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/generator.ts","../src/utils/index.ts"],"names":["MAX_MACHINE_ID","MAX_SEQUENCE","MACHINE_ID_SHIFT","TIMESTAMP_SHIFT","DEFAULT_EPOCH","SnowflakeGenerator","config","machineId","epoch","clockMoveBackAction","ts","drift","createGenerator","SEQUENCE_MASK","MACHINE_ID_MASK","parseSnowflake","id","sfId","timestampMs","stringifySnowflakeParts","parts","getTimestamp","getMachineId","getSequence","isValidSnowflake","relaxed","snowflakeToString","stringToSnowflake","str","compareSnowflakes","a","b","idA","idB","snowflakeFromTimestamp","date","sequence"],"mappings":"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","file":"index.js","sourcesContent":["import type { SnowflakeConfig } from '../types/type';\n\nconst MAX_MACHINE_ID = 1023;\nconst MAX_SEQUENCE = 4095n;\nconst MACHINE_ID_SHIFT = 12n;\nconst TIMESTAMP_SHIFT = 22n;\nconst DEFAULT_EPOCH = 1704067200000;\nconst MAX_CLOCK_WAIT_MS = 50;\n\n/**\n * Generates 64-bit, time-sortable unique IDs.\n */\nexport class SnowflakeGenerator {\n    private readonly machineIdShifted: bigint;\n    private readonly epoch: number;\n    private readonly clockMoveBackAction: 'throw' | 'wait';\n    private sequence = 0n;\n    private lastTimestamp = -1;\n\n    constructor(config: SnowflakeConfig) {\n        const { machineId, epoch = DEFAULT_EPOCH, clockMoveBackAction = 'throw' } = config;\n\n        if (machineId < 0 || machineId > MAX_MACHINE_ID || !Number.isInteger(machineId)) {\n            throw new Error(`machineId must be integer 0-1023, got ${machineId}`);\n        }\n\n        if (epoch < 0 || epoch > Date.now()) {\n            throw new Error(`epoch cannot be in the future`);\n        }\n\n        this.machineIdShifted = BigInt(machineId) << MACHINE_ID_SHIFT;\n        this.epoch = epoch;\n        this.clockMoveBackAction = clockMoveBackAction;\n    }\n\n    /**\n     * @throws Error if the system clock drifts backwards.\n     */\n    nextId(): bigint {\n        let ts = Date.now();\n\n        if (ts < this.lastTimestamp) {\n            const drift = this.lastTimestamp - ts;\n\n            if (this.clockMoveBackAction === 'wait' && drift <= MAX_CLOCK_WAIT_MS) {\n                while (ts <= this.lastTimestamp) {\n                    ts = Date.now();\n                }\n            } else {\n                throw new Error(`Clock moved backwards by ${drift}ms`);\n            }\n        }\n\n        if (ts === this.lastTimestamp) {\n            this.sequence = (this.sequence + 1n) & MAX_SEQUENCE;\n            if (this.sequence === 0n) {\n                while (ts <= this.lastTimestamp) {\n                    ts = Date.now();\n                }\n            }\n        } else {\n            this.sequence = 0n;\n        }\n\n        this.lastTimestamp = ts;\n        return (BigInt(ts - this.epoch) << TIMESTAMP_SHIFT) | this.machineIdShifted | this.sequence;\n    }\n\n    nextIdString(): string {\n        return this.nextId().toString();\n    }\n\n    getMachineId(): number {\n        return Number(this.machineIdShifted >> MACHINE_ID_SHIFT);\n    }\n\n    getEpoch(): number {\n        return this.epoch;\n    }\n\n    getSequence(): number {\n        return Number(this.sequence);\n    }\n\n    getLastTimestamp(): number {\n        return this.lastTimestamp;\n    }\n}\n\nexport function createGenerator(config: SnowflakeConfig): SnowflakeGenerator {\n    return new SnowflakeGenerator(config);\n}\n\nexport {\n    MAX_SEQUENCE,\n    MACHINE_ID_SHIFT,\n    TIMESTAMP_SHIFT,\n    DEFAULT_EPOCH,\n    MAX_MACHINE_ID,\n};","import type { SnowflakeParts, SnowflakePartsJSON } from '../types/type';\nimport {\n    MACHINE_ID_SHIFT,\n    TIMESTAMP_SHIFT,\n    DEFAULT_EPOCH,\n    MAX_SEQUENCE,\n    MAX_MACHINE_ID\n} from '../core/generator';\n\nconst SEQUENCE_MASK = MAX_SEQUENCE;\nconst MACHINE_ID_MASK = BigInt(MAX_MACHINE_ID);\n\nexport function parseSnowflake(id: bigint | string, epoch = DEFAULT_EPOCH): SnowflakeParts {\n    if (typeof id === 'string' && !/^\\d+$/.test(id)) {\n        throw new Error(`Invalid Snowflake ID: \"${id}\"`);\n    }\n\n    const sfId = typeof id === 'string' ? BigInt(id) : id;\n    const timestampMs = Number(sfId >> TIMESTAMP_SHIFT) + epoch;\n\n    return {\n        id: sfId,\n        timestamp: new Date(timestampMs),\n        timestampMs,\n        machineId: Number((sfId >> MACHINE_ID_SHIFT) & MACHINE_ID_MASK),\n        sequence: Number(sfId & SEQUENCE_MASK),\n    };\n}\n\nexport function stringifySnowflakeParts(parts: SnowflakeParts): SnowflakePartsJSON {\n    return {\n        id: parts.id.toString(),\n        timestamp: parts.timestamp.toISOString(),\n        timestampMs: parts.timestampMs,\n        machineId: parts.machineId,\n        sequence: parts.sequence,\n    };\n}\n\nexport function getTimestamp(id: bigint | string, epoch = DEFAULT_EPOCH): Date {\n    const sfId = typeof id === 'string' ? BigInt(id) : id;\n    return new Date(Number(sfId >> TIMESTAMP_SHIFT) + epoch);\n}\n\nexport function getMachineId(id: bigint | string): number {\n    const sfId = typeof id === 'string' ? BigInt(id) : id;\n    return Number((sfId >> MACHINE_ID_SHIFT) & MACHINE_ID_MASK);\n}\n\nexport function getSequence(id: bigint | string): number {\n    const sfId = typeof id === 'string' ? BigInt(id) : id;\n    return Number(sfId & SEQUENCE_MASK);\n}\n\n/**\n * @param relaxed - Skip timestamp range check.\n */\nexport function isValidSnowflake(id: unknown, epoch = DEFAULT_EPOCH, relaxed = false): boolean {\n    if (typeof id === 'string') {\n        if (!/^\\d+$/.test(id)) return false;\n        try {\n            id = BigInt(id);\n        } catch {\n            return false;\n        }\n    }\n\n    if (typeof id !== 'bigint' || id < 0n) return false;\n    if (relaxed) return true;\n\n    const ts = Number(id >> TIMESTAMP_SHIFT) + epoch;\n    return ts >= epoch && ts <= Date.now() + 1000;\n}\n\nexport function snowflakeToString(id: bigint): string {\n    return id.toString();\n}\n\nexport function stringToSnowflake(str: string): bigint {\n    if (!/^\\d+$/.test(str)) {\n        throw new Error(`Invalid Snowflake ID string: \"${str}\"`);\n    }\n    return BigInt(str);\n}\n\nexport function compareSnowflakes(a: bigint | string, b: bigint | string): -1 | 0 | 1 {\n    const idA = typeof a === 'string' ? BigInt(a) : a;\n    const idB = typeof b === 'string' ? BigInt(b) : b;\n    return idA < idB ? -1 : idA > idB ? 1 : 0;\n}\n\nexport function snowflakeFromTimestamp(\n    date: Date | number,\n    machineId = 0,\n    sequence = 0,\n    epoch = DEFAULT_EPOCH\n): bigint {\n    const ts = typeof date === 'number' ? date : date.getTime();\n    return (BigInt(ts - epoch) << TIMESTAMP_SHIFT) | (BigInt(machineId) << MACHINE_ID_SHIFT) | BigInt(sequence);\n}"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@toolkit-f/snowflake-id",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Unique ID Generator For NodeJS",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:bm": "vitest run tests/benchmark.test.ts",
+    "test:co": "vitest run tests/collision.test.ts",
+    "test:ut": "vitest run tests/utils.test.ts",
+    "test:watch": "vitest --watch",
+    "test:dist:js": "node tests/dist.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maulik-mk/Snowflake-Id.git"
+  },
+  "keywords": [
+    "snowflake",
+    "id",
+    "uuid",
+    "unique-id",
+    "distributed",
+    "typescript",
+    "generator"
+  ],
+  "author": "Maulik M. K.",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/maulik-mk/Snowflake-Id/issues"
+  },
+  "homepage": "https://github.com/maulik-mk/Snowflake-Id#readme",
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  }
+}