{"_id":"@anglinb/city-hash","_rev":"3-dffccb9f4137a92d052878802138efbb","name":"@anglinb/city-hash","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@anglinb/city-hash","version":"1.0.0","keywords":["hash","cityhash","cityhash64","non-cryptographic","hash-function","typescript"],"author":{"name":"Brian Anglin"},"license":"MIT","_id":"@anglinb/city-hash@1.0.0","maintainers":[{"name":"anglinb","email":"brianranglin@gmail.com"}],"homepage":"https://github.com/anglinb/city-hash#readme","bugs":{"url":"https://github.com/anglinb/city-hash/issues"},"dist":{"shasum":"58ce9008fca8aae90d6849b14af45d3e6e15d5f9","tarball":"https://registry.npmjs.org/@anglinb/city-hash/-/city-hash-1.0.0.tgz","fileCount":4,"integrity":"sha512-JXNCPj4jBADfwcDxWXQQ+YwF9tVGav+3e8BwFj3XcmoAddGsGnN/uxvUgksPFxYpRrUnv7cT3hFNibjXpXeV1Q==","signatures":[{"sig":"MEQCIEVXCb1i5rzeYMG0kXLJ4nXB4nS55szU4IiEjm4+WAB0AiBPOt5Ml4/bD8HC+nlqoHjVnZx8P+vgTb0IdBhKi0DAyA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10432},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"0222d080f1ef45342996280140eaa0a2991df31a","scripts":{"test":"vitest run","build":"tsc","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"anglinb","actor":{"name":"anglinb","type":"user","email":"brianranglin@gmail.com"},"email":"brianranglin@gmail.com"},"repository":{"url":"git+https://github.com/anglinb/city-hash.git","type":"git"},"_npmVersion":"10.9.2","description":"TypeScript implementation of CityHash64 - fast, non-cryptographic hash function","directories":{},"_nodeVersion":"23.9.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^3.2.4","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/city-hash_1.0.0_1751408642050_0.287333935695522","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@anglinb/city-hash","version":"1.0.1","keywords":["hash","cityhash","cityhash64","non-cryptographic","hash-function","typescript"],"author":{"name":"Brian Anglin"},"license":"MIT","_id":"@anglinb/city-hash@1.0.1","maintainers":[{"name":"anglinb","email":"brianranglin@gmail.com"}],"homepage":"https://github.com/anglinb/city-hash#readme","bugs":{"url":"https://github.com/anglinb/city-hash/issues"},"dist":{"shasum":"4e15437c6d6f0959fc4c32f1dc33404e51169a2d","tarball":"https://registry.npmjs.org/@anglinb/city-hash/-/city-hash-1.0.1.tgz","fileCount":5,"integrity":"sha512-am6YflSZvuHilQT/E/zv+QSJ407EeNY7PmH+d0eC5StAntLI2jGKuAhw1WhPTtBIYEGFHAro90Try+h/qkQpTg==","signatures":[{"sig":"MEYCIQDekiYrgpyMYf3Q5GLQCpmaXI+4DW/ShnT8Z677MqrUpQIhALYv3TBi3mYMQThVP0tmJia3ibOdfcEpgiLg2hECH0Tv","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17171},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"22de7c53653b7e380cd8674e7b41bb9258ec8ea1","scripts":{"test":"vitest run","build":"tsc && tsc -p tsconfig.cjs.json && mv dist-cjs/index.js dist/index.cjs","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"anglinb","actor":{"name":"anglinb","type":"user","email":"brianranglin@gmail.com"},"email":"brianranglin@gmail.com"},"repository":{"url":"git+https://github.com/anglinb/city-hash.git","type":"git"},"_npmVersion":"10.8.2","description":"TypeScript implementation of CityHash64 - fast, non-cryptographic hash function","directories":{},"_nodeVersion":"20.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^3.2.4","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/city-hash_1.0.1_1751422731536_0.4951588437594632","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@anglinb/city-hash","version":"1.1.0","type":"module","description":"TypeScript implementation of CityHash64 - fast, non-cryptographic hash function","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","require":"./dist/index.cjs","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc && tsc -p tsconfig.cjs.json && mv dist-cjs/index.js dist/index.cjs","prepublishOnly":"npm run build","test":"vitest run","test:watch":"vitest"},"keywords":["hash","cityhash","cityhash64","non-cryptographic","hash-function","typescript"],"author":{"name":"Brian Anglin"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/anglinb/city-hash.git"},"publishConfig":{"access":"public"},"devDependencies":{"tsx":"^4.0.0","typescript":"^5.0.0","vitest":"^3.2.4"},"_id":"@anglinb/city-hash@1.1.0","gitHead":"427facba3a3143ff3f1e632bcc9c9e65230d0017","bugs":{"url":"https://github.com/anglinb/city-hash/issues"},"homepage":"https://github.com/anglinb/city-hash#readme","_nodeVersion":"20.18.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-BQ45oNPwbvxWmLMbL0lWKPUxuz4uMKl/8zoWhQV0JDKo5sLP9WY3UL917bzNB4wdtEQZSYub2aUjyDPXroBd0w==","shasum":"2a1395facb0da40bc009cc455c9e565a6ba00be1","tarball":"https://registry.npmjs.org/@anglinb/city-hash/-/city-hash-1.1.0.tgz","fileCount":5,"unpackedSize":22571,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCNDIJMtXzBFSPHBxiSnUk0EeA1eNPT2fcKOQNmQEJhnAIgM4NxCeamOxZJiQrG69XrVghSLq8SJlIz0ekKEWdTb4Q="}]},"_npmUser":{"name":"anglinb","email":"brianranglin@gmail.com","actor":{"name":"anglinb","email":"brianranglin@gmail.com","type":"user"}},"directories":{},"maintainers":[{"name":"anglinb","email":"brianranglin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/city-hash_1.1.0_1752028875694_0.14429442368699053"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-01T22:24:01.922Z","modified":"2025-07-09T02:41:16.019Z","1.0.0":"2025-07-01T22:24:02.217Z","1.0.1":"2025-07-02T02:18:51.733Z","1.1.0":"2025-07-09T02:41:15.848Z"},"bugs":{"url":"https://github.com/anglinb/city-hash/issues"},"author":{"name":"Brian Anglin"},"license":"MIT","homepage":"https://github.com/anglinb/city-hash#readme","keywords":["hash","cityhash","cityhash64","non-cryptographic","hash-function","typescript"],"repository":{"type":"git","url":"git+https://github.com/anglinb/city-hash.git"},"description":"TypeScript implementation of CityHash64 - fast, non-cryptographic hash function","maintainers":[{"name":"anglinb","email":"brianranglin@gmail.com"}],"readme":"# @anglinb/city-hash\n\nA TypeScript implementation of Google's CityHash64 algorithm - a fast, non-cryptographic hash function.\n\n## Installation\n\n```bash\nnpm install @anglinb/city-hash\n```\n\n## Usage\n\n```typescript\nimport { cityHash64, cityHash64NumMax } from '@anglinb/city-hash';\n\n// Hash a string\nconst hash1 = cityHash64(\"hello world\");\nconsole.log(hash1); // 12386028635079221413n\n\n// Hash binary data\nconst data = new Uint8Array([1, 2, 3, 4, 5]);\nconst hash2 = cityHash64(data);\nconsole.log(hash2); // 8996017160742164057n\n\n// The result is always a BigInt\nconst hash3 = cityHash64(\"The quick brown fox jumps over the lazy dog\");\nconsole.log(hash3.toString()); // \"16697807905646383735\"\n\n// Get a JavaScript-safe number (truncated to 53 bits)\nconst safeHash = cityHash64NumMax(\"hello world\");\nconsole.log(safeHash); // 1129659810357413 (safe JavaScript number)\n```\n\n## API\n\n### `cityHash64(input: string | Uint8Array): bigint`\n\nComputes a 64-bit hash of the input data using Google's CityHash algorithm.\n\n**Parameters:**\n- `input`: The data to hash. Can be either a string or a `Uint8Array`.\n\n**Returns:**\n- A 64-bit hash value as a `BigInt`.\n\n### `cityHash64NumMax(input: string | Uint8Array): number`\n\nComputes a CityHash64 hash truncated to JavaScript's `Number.MAX_SAFE_INTEGER` (53 bits).\n\n**Parameters:**\n- `input`: The data to hash. Can be either a string or a `Uint8Array`.\n\n**Returns:**\n- A hash value as a JavaScript `number`, guaranteed to be ≤ `Number.MAX_SAFE_INTEGER`.\n\nThis function is useful when you need to work with hash values in JavaScript contexts that require regular numbers instead of BigInts, such as JSON serialization or certain database operations.\n\n## Features\n\n- **Fast**: Optimized for speed and designed for hash tables\n- **High Quality**: Produces well-distributed hash values with low collision rates\n- **TypeScript**: Full TypeScript support with proper type definitions\n- **Compatible**: Produces identical output to the original C implementation\n- **Flexible**: Accepts both strings and binary data (Uint8Array)\n\n## About CityHash\n\nCityHash is a family of hash functions created by Google for use in hash tables and other applications where speed is more important than cryptographic security. CityHash64 specifically produces 64-bit hash values.\n\nThis implementation:\n- Matches the behavior of the original C implementation exactly\n- Handles both string and binary input data\n- Uses BigInt for proper 64-bit arithmetic in JavaScript\n- Is thoroughly tested with comprehensive test coverage\n\n## ClickHouse Integration\n\nThe `cityHash64NumMax` function is designed to be compatible with ClickHouse database operations. Here's how to reproduce the same truncated hash values in ClickHouse:\n\n### Direct SQL Query\n\n```sql\n-- Get the same result as cityHash64NumMax(\"hello world\")\nSELECT bitAnd(cityHash64('hello world'), 0x1FFFFFFFFFFFFF);\n-- Result: 1129659810357413\n```\n\n### Create a ClickHouse Function\n\nYou can create a user-defined function in ClickHouse to match `cityHash64NumMax`:\n\n```sql\n-- Create a function that matches cityHash64NumMax\nCREATE FUNCTION cityHash64NumMax AS (input) -> bitAnd(cityHash64(input), 0x1FFFFFFFFFFFFF);\n\n-- Usage examples\nSELECT cityHash64NumMax('hello world');           -- 1129659810357413\nSELECT cityHash64NumMax('test string');           -- 7852960286803079\nSELECT cityHash64NumMax('another example');       -- 6487172654247519\n```\n\n### Use in Table Operations\n\n```sql\n-- Create a table with a hash column\nCREATE TABLE user_events (\n    user_id String,\n    event_data String,\n    hash_value UInt64 MATERIALIZED cityHash64NumMax(event_data)\n) ENGINE = MergeTree()\nORDER BY user_id;\n\n-- Insert data (hash_value will be automatically calculated)\nINSERT INTO user_events (user_id, event_data) VALUES \n    ('user1', 'login'),\n    ('user2', 'purchase'),\n    ('user1', 'logout');\n\n-- Query using the hash\nSELECT * FROM user_events WHERE hash_value = cityHash64NumMax('login');\n```\n\n### Consistency Verification\n\nYou can verify that your JavaScript and ClickHouse implementations produce identical results:\n\n```typescript\n// JavaScript\nimport { cityHash64NumMax } from '@anglinb/city-hash';\nconst jsResult = cityHash64NumMax('test input');\nconsole.log(jsResult); // e.g., 1234567890123\n```\n\n```sql\n-- ClickHouse\nSELECT bitAnd(cityHash64('test input'), 0x1FFFFFFFFFFFFF);\n-- Should return the same value: 1234567890123\n```\n\n## Performance\n\nCityHash is designed to be fast on modern processors. This TypeScript implementation maintains good performance while providing the safety and convenience of TypeScript.\n\n## License\n\nMIT\n\n## Credits\n\nBased on the original CityHash algorithm by Geoff Pike and Jyrki Alakuijala at Google.\n- Original C implementation: https://github.com/google/cityhash\n- Algorithm paper: https://github.com/google/cityhash\n","readmeFilename":"README.md"}