{"_id":"@abdulmannan2005/osid","_rev":"2-86406c4f39f8a387f359b92aedfc6c71","name":"@abdulmannan2005/osid","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@abdulmannan2005/osid","version":"1.0.0","keywords":["id","generator","uuid","ulid","snowflake","collision-free","deterministic","crockford","base32"],"author":{"name":"Muhammad Abdul Mannan"},"license":"MIT","_id":"@abdulmannan2005/osid@1.0.0","maintainers":[{"name":"abdulmannan2005","email":"muhammadabdulmannan21@gmail.com"}],"homepage":"https://github.com/muhammadAbdulMannan2022/osid#readme","bugs":{"url":"https://github.com/muhammadAbdulMannan2022/osid/issues"},"dist":{"shasum":"6b557d0b49b68a9302bf0ee3778c651b2fca8f22","tarball":"https://registry.npmjs.org/@abdulmannan2005/osid/-/osid-1.0.0.tgz","fileCount":9,"integrity":"sha512-901cqsZOZNEi/NMR9m7FXY3ztjghgpPNqAo9YrXEQtcC49lnpEWiqxLwh2cIhSAslsWW3hzvmzof12BTO9VYww==","signatures":[{"sig":"MEUCIBrXbmnJHmr3yPXo0qCL/MXTAj5onY/F+GGr7pYSK08GAiEA1S4EkQaJVjYer/oEVxh37oFGI4QzWnJcrDMjbweyAcg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":57105},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"9f725eff150864707a84aea59a5a143f665880ac","scripts":{"test":"vitest run","build":"tsup","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"abdulmannan2005","email":"muhammadabdulmannan21@gmail.com"},"repository":{"url":"git+https://github.com/muhammadAbdulMannan2022/osid.git","type":"git"},"_npmVersion":"11.11.1","description":"Stateless, Deterministic, 160-Bit Collision-Free ID Generator","directories":{},"_nodeVersion":"22.19.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.1.8","typescript":"^5.7.2"},"_npmOperationalInternal":{"tmp":"tmp/osid_1.0.0_1780484559531_0.06679835246257038","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@abdulmannan2005/osid","version":"1.0.1","description":"Stateless, Deterministic, 160-Bit Collision-Free ID Generator","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"keywords":["id","generator","uuid","ulid","snowflake","collision-free","deterministic","crockford","base32"],"repository":{"type":"git","url":"git+https://github.com/muhammadAbdulMannan2022/osid.git"},"bugs":{"url":"https://github.com/muhammadAbdulMannan2022/osid/issues"},"homepage":"https://github.com/muhammadAbdulMannan2022/osid#readme","author":{"name":"Muhammad Abdul Mannan"},"license":"MIT","devDependencies":{"tsup":"^8.3.5","typescript":"^5.7.2","vitest":"^2.1.8"},"gitHead":"85e03cc9308e17ec847765dfe9db4fa0d3bf9efe","_id":"@abdulmannan2005/osid@1.0.1","_nodeVersion":"22.19.0","_npmVersion":"11.11.1","dist":{"integrity":"sha512-om2HuIyjOXt9doAiTX7Xy4sK1KbGXSehTuS8Ffb+lTx6+AGpqBny80v1bJIgvwZ18sHNEZHsBzWaOyAEftho9w==","shasum":"cee5a9a55f9e65000f1a406d238a20d24c634ee9","tarball":"https://registry.npmjs.org/@abdulmannan2005/osid/-/osid-1.0.1.tgz","fileCount":9,"unpackedSize":57140,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGmrfi4r22tt/q4GZt5pPkpdwccf6d3wmB6AJLztrC1pAiEA5n/OdW1l0yr5iVes08PBYFD31Fe6pdYxUtV0c96X6Og="}]},"_npmUser":{"name":"abdulmannan2005","email":"muhammadabdulmannan21@gmail.com"},"directories":{},"maintainers":[{"name":"abdulmannan2005","email":"muhammadabdulmannan21@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/osid_1.0.1_1780546611538_0.13800151214857537"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T11:02:39.372Z","modified":"2026-06-04T04:16:51.795Z","1.0.0":"2026-06-03T11:02:39.676Z","1.0.1":"2026-06-04T04:16:51.703Z"},"bugs":{"url":"https://github.com/muhammadAbdulMannan2022/osid/issues"},"author":{"name":"Muhammad Abdul Mannan"},"license":"MIT","homepage":"https://github.com/muhammadAbdulMannan2022/osid#readme","keywords":["id","generator","uuid","ulid","snowflake","collision-free","deterministic","crockford","base32"],"repository":{"type":"git","url":"git+https://github.com/muhammadAbdulMannan2022/osid.git"},"description":"Stateless, Deterministic, 160-Bit Collision-Free ID Generator","maintainers":[{"name":"abdulmannan2005","email":"muhammadabdulmannan21@gmail.com"}],"readme":"# osid (Omniscience ID)\n\n### The Stateless, Deterministic, 160-Bit Collision-Free ID Generator\n\n`osid` is an ultra-fast, decentralized identity generation protocol designed to eliminate the concept of \"probability\" entirely. It replaces random UUIDs with a deterministic, multi-axis system that guarantees absolute mathematical uniqueness across distributed systems without requiring network communication, database checks, or central coordination.\n\n---\n\n## 1. Core Architecture & Bit Budget\n\n`osid` divides a 160-bit payload into three non-overlapping coordinates spanning Time, Space, and Order:\n\n```\n+------------------------------------+------------------------------------+----------------------------------+\n|             Timestamp              |           Spatial Vector           |         Atomic Sequence          |\n|             (64 Bits)              |             (64 Bits)              |            (32 Bits)             |\n+------------------------------------+------------------------------------+----------------------------------+\n|  <-------- Chronological --------> |  <------- Decentralized -------->  |  <------- Thread Safety -------> |\n|  Microseconds since Jan 1, 2026    |  48-bit Host ID + 16-bit PID       |  4.2B unique counts/microsecond  |\n```\n\n### The Mathematical Formula\n\n```\nI = (T * 2^96) + (S * 2^32) + O\n```\n\nOr via bitwise operators:\n\n```javascript\nI = (T << 96n) | (S << 32n) | O\n```\n\nWhere:\n- **T (Chronological Vector)**: A 64-bit integer tracking elapsed microseconds since the custom epoch (January 1, 2026). Lifespan of 584,542 years before overflow.\n- **S (Spatial Vector)**: A 64-bit coordinate segregating execution environments. Formed by a 48-bit Host ID (derived from network MAC addresses or client uuid hash) and a 16-bit Process ID (`process.pid` or tab/random context).\n- **O (Atomic Sequence)**: A 32-bit local counter handling microsecond-level concurrency bursts inside the execution thread.\n\nBecause no two execution environments can share the same Spatial Vector (S) at the exact same point in Time (T), and no single environment can execute two events on the same step of the Sequence (O), collisions are mathematically impossible:\n\n> **{ T₁, S₁, O₁ } ∩ { T₂, S₂, O₂ } = ∅ for all generations**\n\n---\n\n## 2. Serialization Format\n\n`osid` serializes the 160-bit payload into a custom Crockford's Base32 string.\n\n- **Lexicographical Sortability**: Because the timestamp sits at the higher-order bits, sorting the IDs as strings automatically sorts them by creation time.\n- **Case Insensitivity & Safety**: Uses Crockford's Alphabet (`0123456789ABCDEFGHJKMNPQRSTVWXYZ`), mapping `I`, `L`, `i`, `l` to `1`, and `O`, `o` to `0` during decoding, preventing typo errors and avoiding accidental obscene words (by excluding `U`).\n- **Fixed Clean Layout**: Exactly 32 characters long. E.g., `01H7X1ZA8000003F9A00000000000004`.\n\n---\n\n## 3. Installation\n\nInstall the package into your project:\n\n```bash\nnpm install @abdulmannan2005/osid\n```\n\n---\n\n## 4. Usage Guide\n\n`osid` supports both ES Modules (ESM) and CommonJS (CJS) out-of-the-box.\n\n### ES Modules (ESM)\n\n```typescript\nimport { osid } from \"@abdulmannan2005/osid\";\n\n// Generate a 32-character Base32 ID\nconst id = osid(); \nconsole.log(id); // \"01H7X1ZA8000003F9A00000000000004\"\n\n// Generate a raw 160-bit BigInt\nconst rawId = osid.raw();\nconsole.log(rawId); // 16560940348737222830843187216654286127104n\n```\n\n### CommonJS (CJS)\n\n```javascript\nconst { osid } = require(\"@abdulmannan2005/osid\");\n\nconst id = osid();\nconsole.log(id); // \"01H7X1ZA8000003F9A00000000000004\"\n```\n\n---\n\n## 5. API Reference\n\n### `osid(): string`\nGenerates and returns a 32-character Crockford's Base32 ID.\n\n### `osid.raw(): bigint`\nGenerates and returns the raw 160-bit BigInt ID representation.\n\n### `osid.decode(id: string | bigint): OsidComponents`\nParses any 32-character ID string or 160-bit BigInt back into its mathematical coordinates.\nReturns:\n```typescript\n{\n  timestamp: bigint; // Microseconds since epoch\n  spatial: {\n    hostId: bigint;   // 48-bit host fingerprint\n    processId: number; // 16-bit process ID\n  };\n  sequence: number;   // 32-bit sequence counter\n}\n```\n\n### `osid.info(id: string | bigint): object`\nExtracts components and formats them into a human-readable structure, converting timestamps to ISO dates and Host IDs to MAC-address-like representations.\nReturns:\n```javascript\n{\n  date: \"2026-06-03T10:47:41.000Z\",\n  timestampMicroseconds: \"13258061000\",\n  hostId: \"1879048192n\",\n  hostMacFormatted: \"00:00:70:00:00:00\",\n  processId: 10452,\n  sequence: 0\n}\n```\n\n### `osid.isValid(id: string): boolean`\nValidates if a string is a valid 32-character Crockford Base32 ID (i.e. correct length and only containing valid characters).\n\n### `class OsidGenerator`\nAllows creating customized generator instances. Useful for spoofing space coordinates, resetting state, or running unit tests with smaller boundaries.\n```typescript\nimport { OsidGenerator } from \"@abdulmannan2005/osid\";\n\nconst generator = new OsidGenerator({\n  hostId: 0x112233445566n, // custom 48-bit host footprint\n  processId: 99            // custom 16-bit process ID\n});\n\nconst customId = generator.generateRaw();\n```\n\n---\n\n## 6. Monotonicity & Reliability\n\n### Clock Drift Guard rails\nIn the event that the system clock drifts backwards (e.g. NTP synchronization adjustment), the generator maintains strict monotonicity:\n1. It retains the last known timestamp.\n2. It increments the `sequence` counter until the physical clock catches up.\n\n### Overrun Lock\nIn the event that a process exceeds 4,294,967,296 generated IDs within a single microsecond, the execution thread encounters a deterministic spin-lock. The execution thread halts until the system clock advances by at least 1 microsecond, resetting the sequence counter to 0 and continuing safely.\n\n---\n\n## 7. Development & Verification\n\nTo run tests:\n```bash\nnpm run test\n```\nTo run tests in watch mode:\n```bash\nnpm run test:watch\n```\nTo build the library files:\n```bash\nnpm run build\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}