@alwatr/hash-string 5.1.0 → 5.2.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.2.0](https://github.com/Alwatr/nanolib/compare/@alwatr/hash-string@5.1.0...@alwatr/hash-string@5.2.0) (2025-04-01)
+
+### Features
+
+* implement DJB2 hash algorithm for efficient string hashing ([d505181](https://github.com/Alwatr/nanolib/commit/d505181fed1f85cf067ea5499b3de692b84385b0)) by @alimd
+
+### Bug Fixes
+
+* change default repeat value in hashString function from 3 to 1 ([e5c373f](https://github.com/Alwatr/nanolib/commit/e5c373f2a18ce1933f234a6f8dafeda181df1f14)) by @alimd
+
+### Code Refactoring
+
+* replace hashString function with nanoHash and export new hashing methods ([3651b0c](https://github.com/Alwatr/nanolib/commit/3651b0cf254a044f7eb4cfc0a52a9b645e1c26d3)) by @alimd
+
 ## 5.1.0 (2025-03-18)
 
 ### Features

package/README.md

@@ -1,6 +1,7 @@
 # hash-string
 
-A lightweight, high-performance utility for generating simple non-cryptographic hash strings from input values.
+A lightweight, high-performance utility for generating simple hash strings from input values.  
+It is **non-cryptographic** but very fast and efficient. While it cannot be reversed easily and brute force attacks can take up to years for fast computers.
 
 ## Installation
 
@@ -13,22 +14,22 @@ npm install @alwatr/hash-string
 ## Usage
 
 ```typescript
-import {hashString} from '@alwatr/hash-string';
+import {nanoHash} from '@alwatr/hash-string';
 
 // Hash a string with a prefix
-hashString('test', 'prefix-');  // => 'prefix-j26j3d4'
+nanoHash('test', 'prefix-');  // => 'prefix-j26j3d4'
 
 // Hash a number
-hashString(12345, 'num-');      // => 'num-8hu3f2l'
+nanoHash(12345, 'num-');      // => 'num-8hu3f2l'
 
 // Adjust complexity with repeat parameter
-hashString('test', 'p-', 1);    // => 'p-7ba2n3y' (faster, less complex)
-hashString('test', 'p-', 5);    // => 'p-3f72h9b' (slower, more complex)
+nanoHash('test', 'p-', 1);    // => 'p-7ba2n3y' (faster, less complex)
+nanoHash('test', 'p-', 5);    // => 'p-3f72h9b' (slower, more complex)
 ```
 
 ## API
 
-### hashString(str: string | number, prefix: string, repeat = 3): string
+### nanoHash(str: string | number, prefix: string, repeat = 3): string
 
 Generates a simple hash from the input string or number.
 
@@ -49,7 +50,9 @@ Returns a hashed string with the specified prefix.
 
 ## Security Note
 
-This function is designed for simple hashing needs like generating IDs or checksums. It is **not suitable** for cryptographic purposes or security-sensitive applications. While the output cannot be easily reversed, it's not designed to resist targeted attacks.
+This function is designed for simple hashing needs like generating IDs or checksums. It is **non-cryptographic** but very fast and efficient. While it cannot be reversed easily and brute force attacks can take up to years for fast computers, it is still **not suitable** for security-sensitive applications or storing sensitive data. The algorithm prioritizes speed and simplicity over cryptographic strength, making it ideal for general-purpose hashing where security is not a primary concern.
+
+For security-critical applications, use established cryptographic hash functions (like SHA-256 or Argon2) instead.
 
 ## Examples
 
@@ -57,26 +60,26 @@ This function is designed for simple hashing needs like generating IDs or checks
 
 ```typescript
 // Generate a hash for a string
-hashString('hello world', 'msg-');  // => 'msg-k7f2h9d'
+nanoHash('hello world', 'msg-');  // => 'msg-k7f2h9d'
 
 // Generate a hash for a number
-hashString(42, 'id-');  // => 'id-p83b2e4'
+nanoHash(42, 'id-');  // => 'id-p83b2e4'
 
 // Same input produces the same output
-hashString('test', 'x-') === hashString('test', 'x-');  // => true
+nanoHash('test', 'x-') === nanoHash('test', 'x-');  // => true
 
 // Different inputs produce different outputs
-hashString('test1', 'x-') !== hashString('test2', 'x-');  // => true
+nanoHash('test1', 'x-') !== nanoHash('test2', 'x-');  // => true
 ```
 
 ### Controlling Complexity
 
 ```typescript
 // Less complex (faster)
-hashString('password', 'user-', 1);
+nanoHash('password', 'user-', 1);
 
 // More complex (slightly slower)
-hashString('password', 'user-', 5);
+nanoHash('password', 'user-', 5);
 ```
 
 ### Use Cases
@@ -88,7 +91,7 @@ hashString('password', 'user-', 5);
 
 ## Implementation Details
 
-The hashing algorithm combines two 32-bit hash functions with prime number multipliers to create a distribution with good avalanche properties. This means small changes in the input produce significantly different outputs, reducing collision probability.
+The hashing algorithm combines two 32-bit hash functions with prime number multipliers to create a distribution with good avalanche properties. This means small changes in the input produce significantly different outputs, reducing collision probability. Though non-cryptographic, the algorithm's computational complexity makes it resistant to casual reversal attempts.
 
 The implementation:
 
@@ -98,6 +101,25 @@ The implementation:
 4. Optionally repeats the process for increased complexity
 5. Converts the result to base-36 for compact representation
 
+### DJB2 Hash Algorithm
+
+The package includes the DJB2 hash algorithm, a fast and efficient string hashing function created by Daniel J. Bernstein:
+
+```typescript
+// Generate a numeric hash value
+import {djb2Hash} from '@alwatr/hash-string';
+
+const hashValue = djb2Hash("hello world"); // Returns a 32-bit unsigned integer
+```
+
+Key features of djb2Hash:
+
+- Fast computation with minimal operations
+- Produces consistent 32-bit unsigned integer values
+- Good distribution for short to medium-length strings
+- Simple implementation with right-to-left iteration for performance
+- Uses prime number (5381) as the initial seed
+
 ## Sponsors
 
 The following companies, organizations, and individuals support Nanolib ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.

package/dist/djb2-hash.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DJB2 Hash Algorithm - A fast string hashing function.
+ *
+ * This implementation is based on Daniel J. Bernstein's popular 'times 33' hash algorithm,
+ * commonly known as DJB2. It's known for its simplicity, speed, and good distribution properties
+ * for short strings, making it suitable for general purpose hashing needs.
+ *
+ * Performance notes:
+ * - Uses right-to-left iteration to avoid repeated length lookups
+ * - Employs bit shifting operations for faster computation
+ * - Final right shift ensures unsigned 32-bit integer output
+ *
+ * @param {string} str - The input string to be hashed
+ * @returns {number} A 32-bit unsigned integer hash value
+ *
+ * @example
+ * // Returns a numeric hash value
+ * const hashValue = djb2Hash("hello world");
+ */
+export declare function djb2Hash(str: string): number;
+//# sourceMappingURL=djb2-hash.d.ts.map

package/dist/djb2-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"djb2-hash.d.ts","sourceRoot":"","sources":["../src/djb2-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAY5C"}

package/dist/main.cjs

@@ -1,4 +1,4 @@
-/* @alwatr/hash-string v5.1.0 */
+/* @alwatr/hash-string v5.2.0 */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -21,12 +21,23 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/main.ts
 var main_exports = {};
 __export(main_exports, {
-  hashString: () => hashString
+  djb2Hash: () => djb2Hash,
+  nanoHash: () => nanoHash
 });
 module.exports = __toCommonJS(main_exports);
 var import_package_tracer = require("@alwatr/package-tracer");
-__dev_mode__: import_package_tracer.packageTracer.add("@alwatr/hash-string", "5.1.0");
-function hashString(str, prefix, repeat = 3) {
+
+// src/djb2-hash.ts
+function djb2Hash(str) {
+  let hashValue = 5381;
+  for (let i = str.length - 1; i >= 0; i--) {
+    hashValue = (hashValue << 5) + hashValue ^ str.charCodeAt(i);
+  }
+  return hashValue >>> 0;
+}
+
+// src/nano-hash.ts
+function nanoHash(str, prefix, repeat = 1) {
   if (repeat < 1) {
     throw new Error("The repeat parameter must be greater than or equal to 1");
   }
@@ -35,7 +46,8 @@ function hashString(str, prefix, repeat = 3) {
   if (typeof str === "number") {
     str = str.toString();
   }
-  for (let i = 0; i < str.length; i++) {
+  const len = str.length;
+  for (let i = 0; i < len; i++) {
     const char = str.charCodeAt(i);
     hash1 = Math.imul(hash1 ^ char, 2654435761);
     hash2 = Math.imul(hash2 ^ char, 1597334677);
@@ -46,11 +58,15 @@ function hashString(str, prefix, repeat = 3) {
   if (repeat === 1) {
     return result;
   } else {
-    return hashString(result, prefix, repeat - 1);
+    return nanoHash(result, prefix, repeat - 1);
   }
 }
+
+// src/main.ts
+__dev_mode__: import_package_tracer.packageTracer.add("@alwatr/hash-string", "5.2.0");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  hashString
+  djb2Hash,
+  nanoHash
 });
 //# sourceMappingURL=main.cjs.map

package/dist/main.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/main.ts"],
-  "sourcesContent": ["import {packageTracer} from '@alwatr/package-tracer';\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\n/**\n * Simple hash string for fast hashing (like md5).\n * This function is not very secure and should not be used for security purposes.\n * But it cannot be reversed easily and brute force can take up to years for very fast computers.\n *\n * @param str - The string or number to hash\n * @param prefix - A prefix to add to the beginning of the hash result\n * @param repeat - Number of times to repeat the hashing process for increased complexity (default: 3)\n * @returns A hashed string with the specified prefix\n */\nexport function hashString(str: string | number, prefix: string, repeat = 3): string {\n  if (repeat < 1) {\n    throw new Error('The repeat parameter must be greater than or equal to 1');\n  }\n\n  let hash1 = 0xdeadbeef;\n  let hash2 = 0x41c6ce57;\n\n  if (typeof str === 'number') {\n    str = str.toString();\n  }\n\n  for (let i = 0; i < str.length; i++) {\n    const char = str.charCodeAt(i);\n    hash1 = Math.imul(hash1 ^ char, 2654435761);\n    hash2 = Math.imul(hash2 ^ char, 1597334677);\n  }\n\n  hash1 = Math.imul(hash1 ^ (hash1 >>> 16), 2246822507) ^ Math.imul(hash2 ^ (hash2 >>> 13), 3266489909);\n  hash2 = Math.imul(hash2 ^ (hash2 >>> 16), 2246822507) ^ Math.imul(hash1 ^ (hash1 >>> 13), 3266489909);\n\n  const result = prefix + (hash1 >>> 0).toString(36) + (hash2 >>> 0).toString(36);\n  if (repeat === 1) {\n    return result;\n  }\n  else {\n    return hashString(result, prefix, repeat - 1);\n  }\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,4BAA4B;AAE5B,aAAc,qCAAc,IAAI,uBAAkB,OAAmB;AAY9D,SAAS,WAAW,KAAsB,QAAgB,SAAS,GAAW;AACnF,MAAI,SAAS,GAAG;AACd,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AAEA,MAAI,QAAQ;AACZ,MAAI,QAAQ;AAEZ,MAAI,OAAO,QAAQ,UAAU;AAC3B,UAAM,IAAI,SAAS;AAAA,EACrB;AAEA,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,UAAM,OAAO,IAAI,WAAW,CAAC;AAC7B,YAAQ,KAAK,KAAK,QAAQ,MAAM,UAAU;AAC1C,YAAQ,KAAK,KAAK,QAAQ,MAAM,UAAU;AAAA,EAC5C;AAEA,UAAQ,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU,IAAI,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU;AACpG,UAAQ,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU,IAAI,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU;AAEpG,QAAM,SAAS,UAAU,UAAU,GAAG,SAAS,EAAE,KAAK,UAAU,GAAG,SAAS,EAAE;AAC9E,MAAI,WAAW,GAAG;AAChB,WAAO;AAAA,EACT,OACK;AACH,WAAO,WAAW,QAAQ,QAAQ,SAAS,CAAC;AAAA,EAC9C;AACF;",
+  "sources": ["../src/main.ts", "../src/djb2-hash.ts", "../src/nano-hash.ts"],
+  "sourcesContent": ["import {packageTracer} from '@alwatr/package-tracer';\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\nexport * from './djb2-hash.js';\nexport * from './nano-hash.js';\n", "/**\n * DJB2 Hash Algorithm - A fast string hashing function.\n *\n * This implementation is based on Daniel J. Bernstein's popular 'times 33' hash algorithm,\n * commonly known as DJB2. It's known for its simplicity, speed, and good distribution properties\n * for short strings, making it suitable for general purpose hashing needs.\n *\n * Performance notes:\n * - Uses right-to-left iteration to avoid repeated length lookups\n * - Employs bit shifting operations for faster computation\n * - Final right shift ensures unsigned 32-bit integer output\n *\n * @param {string} str - The input string to be hashed\n * @returns {number} A 32-bit unsigned integer hash value\n *\n * @example\n * // Returns a numeric hash value\n * const hashValue = djb2Hash(\"hello world\");\n */\nexport function djb2Hash(str: string): number {\n  // 5381 is a prime number used as initial value in the DJB2 algorithm\n  let hashValue = 5381;\n\n  // Reverse loop for better performance - avoids repeated length property lookup\n  for (let i = str.length - 1; i >= 0; i--) {\n    // Using left shift (*2) and addition instead of multiplication by 33\n    // (hash * 33) is equivalent to ((hash << 5) + hash)\n    hashValue = ((hashValue << 5) + hashValue) ^ str.charCodeAt(i);\n  }\n\n  return hashValue >>> 0;\n}\n", "/**\n * Simple hash string for fast hashing (like md5).\n * This function is not very secure and should not be used for security purposes.\n * But it cannot be reversed easily and brute force can take up to years for fast computers.\n *\n * @param str - The string or number to hash\n * @param prefix - A prefix to add to the beginning of the hash result\n * @param repeat - Number of times to repeat the hashing process for increased complexity (default: 3)\n * @returns A hashed string with the specified prefix\n */\nexport function nanoHash(str: string | number, prefix: string, repeat = 1): string {\n  if (repeat < 1) {\n    throw new Error('The repeat parameter must be greater than or equal to 1');\n  }\n\n  let hash1 = 0xdeadbeef;\n  let hash2 = 0x41c6ce57;\n\n  if (typeof str === 'number') {\n    str = str.toString();\n  }\n\n  const len = str.length;\n  for (let i = 0; i < len; i++) {\n    const char = str.charCodeAt(i);\n    hash1 = Math.imul(hash1 ^ char, 2654435761);\n    hash2 = Math.imul(hash2 ^ char, 1597334677);\n  }\n\n  hash1 = Math.imul(hash1 ^ (hash1 >>> 16), 2246822507) ^ Math.imul(hash2 ^ (hash2 >>> 13), 3266489909);\n  hash2 = Math.imul(hash2 ^ (hash2 >>> 16), 2246822507) ^ Math.imul(hash1 ^ (hash1 >>> 13), 3266489909);\n\n  const result = prefix + (hash1 >>> 0).toString(36) + (hash2 >>> 0).toString(36);\n  if (repeat === 1) {\n    return result;\n  }\n  else {\n    return nanoHash(result, prefix, repeat - 1);\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,4BAA4B;;;ACmBrB,SAAS,SAAS,KAAqB;AAE5C,MAAI,YAAY;AAGhB,WAAS,IAAI,IAAI,SAAS,GAAG,KAAK,GAAG,KAAK;AAGxC,iBAAc,aAAa,KAAK,YAAa,IAAI,WAAW,CAAC;AAAA,EAC/D;AAEA,SAAO,cAAc;AACvB;;;ACrBO,SAAS,SAAS,KAAsB,QAAgB,SAAS,GAAW;AACjF,MAAI,SAAS,GAAG;AACd,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AAEA,MAAI,QAAQ;AACZ,MAAI,QAAQ;AAEZ,MAAI,OAAO,QAAQ,UAAU;AAC3B,UAAM,IAAI,SAAS;AAAA,EACrB;AAEA,QAAM,MAAM,IAAI;AAChB,WAAS,IAAI,GAAG,IAAI,KAAK,KAAK;AAC5B,UAAM,OAAO,IAAI,WAAW,CAAC;AAC7B,YAAQ,KAAK,KAAK,QAAQ,MAAM,UAAU;AAC1C,YAAQ,KAAK,KAAK,QAAQ,MAAM,UAAU;AAAA,EAC5C;AAEA,UAAQ,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU,IAAI,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU;AACpG,UAAQ,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU,IAAI,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU;AAEpG,QAAM,SAAS,UAAU,UAAU,GAAG,SAAS,EAAE,KAAK,UAAU,GAAG,SAAS,EAAE;AAC9E,MAAI,WAAW,GAAG;AAChB,WAAO;AAAA,EACT,OACK;AACH,WAAO,SAAS,QAAQ,QAAQ,SAAS,CAAC;AAAA,EAC5C;AACF;;;AFrCA,aAAc,qCAAc,IAAI,uBAAkB,OAAmB;",
   "names": []
 }

package/dist/main.d.ts

@@ -1,12 +1,3 @@
-/**
- * Simple hash string for fast hashing (like md5).
- * This function is not very secure and should not be used for security purposes.
- * But it cannot be reversed easily and brute force can take up to years for very fast computers.
- *
- * @param str - The string or number to hash
- * @param prefix - A prefix to add to the beginning of the hash result
- * @param repeat - Number of times to repeat the hashing process for increased complexity (default: 3)
- * @returns A hashed string with the specified prefix
- */
-export declare function hashString(str: string | number, prefix: string, repeat?: number): string;
+export * from './djb2-hash.js';
+export * from './nano-hash.js';
 //# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,MAAM,CA4BnF"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/main.mjs

@@ -1,9 +1,19 @@
-/* @alwatr/hash-string v5.1.0 */
+/* @alwatr/hash-string v5.2.0 */
 
 // src/main.ts
 import { packageTracer } from "@alwatr/package-tracer";
-__dev_mode__: packageTracer.add("@alwatr/hash-string", "5.1.0");
-function hashString(str, prefix, repeat = 3) {
+
+// src/djb2-hash.ts
+function djb2Hash(str) {
+  let hashValue = 5381;
+  for (let i = str.length - 1; i >= 0; i--) {
+    hashValue = (hashValue << 5) + hashValue ^ str.charCodeAt(i);
+  }
+  return hashValue >>> 0;
+}
+
+// src/nano-hash.ts
+function nanoHash(str, prefix, repeat = 1) {
   if (repeat < 1) {
     throw new Error("The repeat parameter must be greater than or equal to 1");
   }
@@ -12,7 +22,8 @@ function hashString(str, prefix, repeat = 3) {
   if (typeof str === "number") {
     str = str.toString();
   }
-  for (let i = 0; i < str.length; i++) {
+  const len = str.length;
+  for (let i = 0; i < len; i++) {
     const char = str.charCodeAt(i);
     hash1 = Math.imul(hash1 ^ char, 2654435761);
     hash2 = Math.imul(hash2 ^ char, 1597334677);
@@ -23,10 +34,14 @@ function hashString(str, prefix, repeat = 3) {
   if (repeat === 1) {
     return result;
   } else {
-    return hashString(result, prefix, repeat - 1);
+    return nanoHash(result, prefix, repeat - 1);
   }
 }
+
+// src/main.ts
+__dev_mode__: packageTracer.add("@alwatr/hash-string", "5.2.0");
 export {
-  hashString
+  djb2Hash,
+  nanoHash
 };
 //# sourceMappingURL=main.mjs.map

package/dist/main.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/main.ts"],
-  "sourcesContent": ["import {packageTracer} from '@alwatr/package-tracer';\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\n/**\n * Simple hash string for fast hashing (like md5).\n * This function is not very secure and should not be used for security purposes.\n * But it cannot be reversed easily and brute force can take up to years for very fast computers.\n *\n * @param str - The string or number to hash\n * @param prefix - A prefix to add to the beginning of the hash result\n * @param repeat - Number of times to repeat the hashing process for increased complexity (default: 3)\n * @returns A hashed string with the specified prefix\n */\nexport function hashString(str: string | number, prefix: string, repeat = 3): string {\n  if (repeat < 1) {\n    throw new Error('The repeat parameter must be greater than or equal to 1');\n  }\n\n  let hash1 = 0xdeadbeef;\n  let hash2 = 0x41c6ce57;\n\n  if (typeof str === 'number') {\n    str = str.toString();\n  }\n\n  for (let i = 0; i < str.length; i++) {\n    const char = str.charCodeAt(i);\n    hash1 = Math.imul(hash1 ^ char, 2654435761);\n    hash2 = Math.imul(hash2 ^ char, 1597334677);\n  }\n\n  hash1 = Math.imul(hash1 ^ (hash1 >>> 16), 2246822507) ^ Math.imul(hash2 ^ (hash2 >>> 13), 3266489909);\n  hash2 = Math.imul(hash2 ^ (hash2 >>> 16), 2246822507) ^ Math.imul(hash1 ^ (hash1 >>> 13), 3266489909);\n\n  const result = prefix + (hash1 >>> 0).toString(36) + (hash2 >>> 0).toString(36);\n  if (repeat === 1) {\n    return result;\n  }\n  else {\n    return hashString(result, prefix, repeat - 1);\n  }\n}\n"],
-  "mappings": ";;;AAAA,SAAQ,qBAAoB;AAE5B,aAAc,eAAc,IAAI,uBAAkB,OAAmB;AAY9D,SAAS,WAAW,KAAsB,QAAgB,SAAS,GAAW;AACnF,MAAI,SAAS,GAAG;AACd,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AAEA,MAAI,QAAQ;AACZ,MAAI,QAAQ;AAEZ,MAAI,OAAO,QAAQ,UAAU;AAC3B,UAAM,IAAI,SAAS;AAAA,EACrB;AAEA,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,UAAM,OAAO,IAAI,WAAW,CAAC;AAC7B,YAAQ,KAAK,KAAK,QAAQ,MAAM,UAAU;AAC1C,YAAQ,KAAK,KAAK,QAAQ,MAAM,UAAU;AAAA,EAC5C;AAEA,UAAQ,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU,IAAI,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU;AACpG,UAAQ,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU,IAAI,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU;AAEpG,QAAM,SAAS,UAAU,UAAU,GAAG,SAAS,EAAE,KAAK,UAAU,GAAG,SAAS,EAAE;AAC9E,MAAI,WAAW,GAAG;AAChB,WAAO;AAAA,EACT,OACK;AACH,WAAO,WAAW,QAAQ,QAAQ,SAAS,CAAC;AAAA,EAC9C;AACF;",
+  "sources": ["../src/main.ts", "../src/djb2-hash.ts", "../src/nano-hash.ts"],
+  "sourcesContent": ["import {packageTracer} from '@alwatr/package-tracer';\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\nexport * from './djb2-hash.js';\nexport * from './nano-hash.js';\n", "/**\n * DJB2 Hash Algorithm - A fast string hashing function.\n *\n * This implementation is based on Daniel J. Bernstein's popular 'times 33' hash algorithm,\n * commonly known as DJB2. It's known for its simplicity, speed, and good distribution properties\n * for short strings, making it suitable for general purpose hashing needs.\n *\n * Performance notes:\n * - Uses right-to-left iteration to avoid repeated length lookups\n * - Employs bit shifting operations for faster computation\n * - Final right shift ensures unsigned 32-bit integer output\n *\n * @param {string} str - The input string to be hashed\n * @returns {number} A 32-bit unsigned integer hash value\n *\n * @example\n * // Returns a numeric hash value\n * const hashValue = djb2Hash(\"hello world\");\n */\nexport function djb2Hash(str: string): number {\n  // 5381 is a prime number used as initial value in the DJB2 algorithm\n  let hashValue = 5381;\n\n  // Reverse loop for better performance - avoids repeated length property lookup\n  for (let i = str.length - 1; i >= 0; i--) {\n    // Using left shift (*2) and addition instead of multiplication by 33\n    // (hash * 33) is equivalent to ((hash << 5) + hash)\n    hashValue = ((hashValue << 5) + hashValue) ^ str.charCodeAt(i);\n  }\n\n  return hashValue >>> 0;\n}\n", "/**\n * Simple hash string for fast hashing (like md5).\n * This function is not very secure and should not be used for security purposes.\n * But it cannot be reversed easily and brute force can take up to years for fast computers.\n *\n * @param str - The string or number to hash\n * @param prefix - A prefix to add to the beginning of the hash result\n * @param repeat - Number of times to repeat the hashing process for increased complexity (default: 3)\n * @returns A hashed string with the specified prefix\n */\nexport function nanoHash(str: string | number, prefix: string, repeat = 1): string {\n  if (repeat < 1) {\n    throw new Error('The repeat parameter must be greater than or equal to 1');\n  }\n\n  let hash1 = 0xdeadbeef;\n  let hash2 = 0x41c6ce57;\n\n  if (typeof str === 'number') {\n    str = str.toString();\n  }\n\n  const len = str.length;\n  for (let i = 0; i < len; i++) {\n    const char = str.charCodeAt(i);\n    hash1 = Math.imul(hash1 ^ char, 2654435761);\n    hash2 = Math.imul(hash2 ^ char, 1597334677);\n  }\n\n  hash1 = Math.imul(hash1 ^ (hash1 >>> 16), 2246822507) ^ Math.imul(hash2 ^ (hash2 >>> 13), 3266489909);\n  hash2 = Math.imul(hash2 ^ (hash2 >>> 16), 2246822507) ^ Math.imul(hash1 ^ (hash1 >>> 13), 3266489909);\n\n  const result = prefix + (hash1 >>> 0).toString(36) + (hash2 >>> 0).toString(36);\n  if (repeat === 1) {\n    return result;\n  }\n  else {\n    return nanoHash(result, prefix, repeat - 1);\n  }\n}\n"],
+  "mappings": ";;;AAAA,SAAQ,qBAAoB;;;ACmBrB,SAAS,SAAS,KAAqB;AAE5C,MAAI,YAAY;AAGhB,WAAS,IAAI,IAAI,SAAS,GAAG,KAAK,GAAG,KAAK;AAGxC,iBAAc,aAAa,KAAK,YAAa,IAAI,WAAW,CAAC;AAAA,EAC/D;AAEA,SAAO,cAAc;AACvB;;;ACrBO,SAAS,SAAS,KAAsB,QAAgB,SAAS,GAAW;AACjF,MAAI,SAAS,GAAG;AACd,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AAEA,MAAI,QAAQ;AACZ,MAAI,QAAQ;AAEZ,MAAI,OAAO,QAAQ,UAAU;AAC3B,UAAM,IAAI,SAAS;AAAA,EACrB;AAEA,QAAM,MAAM,IAAI;AAChB,WAAS,IAAI,GAAG,IAAI,KAAK,KAAK;AAC5B,UAAM,OAAO,IAAI,WAAW,CAAC;AAC7B,YAAQ,KAAK,KAAK,QAAQ,MAAM,UAAU;AAC1C,YAAQ,KAAK,KAAK,QAAQ,MAAM,UAAU;AAAA,EAC5C;AAEA,UAAQ,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU,IAAI,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU;AACpG,UAAQ,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU,IAAI,KAAK,KAAK,QAAS,UAAU,IAAK,UAAU;AAEpG,QAAM,SAAS,UAAU,UAAU,GAAG,SAAS,EAAE,KAAK,UAAU,GAAG,SAAS,EAAE;AAC9E,MAAI,WAAW,GAAG;AAChB,WAAO;AAAA,EACT,OACK;AACH,WAAO,SAAS,QAAQ,QAAQ,SAAS,CAAC;AAAA,EAC5C;AACF;;;AFrCA,aAAc,eAAc,IAAI,uBAAkB,OAAmB;",
   "names": []
 }

package/dist/nano-hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Simple hash string for fast hashing (like md5).
+ * This function is not very secure and should not be used for security purposes.
+ * But it cannot be reversed easily and brute force can take up to years for fast computers.
+ *
+ * @param str - The string or number to hash
+ * @param prefix - A prefix to add to the beginning of the hash result
+ * @param repeat - Number of times to repeat the hashing process for increased complexity (default: 3)
+ * @returns A hashed string with the specified prefix
+ */
+export declare function nanoHash(str: string | number, prefix: string, repeat?: number): string;
+//# sourceMappingURL=nano-hash.d.ts.map

package/dist/nano-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nano-hash.d.ts","sourceRoot":"","sources":["../src/nano-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,MAAM,CA6BjF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/hash-string",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "A simple utility to generate a hash string.",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com>",
   "keywords": [
@@ -71,14 +71,14 @@
     "clean": "rm -rfv dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@alwatr/package-tracer": "^5.5.1"
+    "@alwatr/package-tracer": "^5.5.2"
   },
   "devDependencies": {
-    "@alwatr/nano-build": "^5.5.1",
+    "@alwatr/nano-build": "^5.5.2",
     "@alwatr/prettier-config": "^5.0.0",
     "@alwatr/tsconfig-base": "^5.0.0",
     "jest": "^29.7.0",
     "typescript": "^5.8.2"
   },
-  "gitHead": "21cb1fe0f26a580944d9e72a313fc99308cd8be7"
+  "gitHead": "2756475ba2fa108bae7af6d8d9747e0c7815dfa2"
 }

package/src/djb2-hash.test.js

@@ -0,0 +1,72 @@
+import {djb2Hash} from '@alwatr/hash-string';
+
+describe('djb2Hash', () => {
+  it('should generate numeric hash values for string inputs', () => {
+    const result = djb2Hash('test');
+    expect(typeof result).toBe('number');
+    expect(Number.isInteger(result)).toBe(true);
+  });
+
+  it('should return different hashes for different inputs', () => {
+    const hash1 = djb2Hash('test1');
+    const hash2 = djb2Hash('test2');
+    expect(hash1).not.toBe(hash2);
+  });
+
+  it('should generate consistent hashes for the same input', () => {
+    const input = 'consistencyTest';
+    const hash1 = djb2Hash(input);
+    const hash2 = djb2Hash(input);
+    expect(hash1).toBe(hash2);
+  });
+
+  it('should handle empty strings', () => {
+    const result = djb2Hash('');
+    expect(typeof result).toBe('number');
+    // The hash for an empty string should be the initial value right-shifted by 0
+    expect(result).toBe(5381 >>> 0);
+  });
+
+  it('should handle special characters', () => {
+    const result = djb2Hash('!@#$%^&*()');
+    expect(typeof result).toBe('number');
+    expect(Number.isInteger(result)).toBe(true);
+  });
+
+  it('should handle long strings', () => {
+    const longString = 'a'.repeat(1000);
+    const result = djb2Hash(longString);
+    expect(typeof result).toBe('number');
+    expect(Number.isInteger(result)).toBe(true);
+  });
+
+  it('should handle Unicode characters', () => {
+    const unicodeString = '😀🌍🚀';
+    const result = djb2Hash(unicodeString);
+    expect(typeof result).toBe('number');
+    expect(Number.isInteger(result)).toBe(true);
+  });
+
+  it('should produce 32-bit unsigned integer outputs', () => {
+    const inputs = ['test', 'hello world', 'unicode 😀', 'a'.repeat(1000)];
+
+    for (const input of inputs) {
+      const result = djb2Hash(input);
+      expect(result).toBeLessThanOrEqual(0xFFFFFFFF); // Max 32-bit unsigned int
+      expect(result).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('should produce deterministic results', () => {
+    // Test with known hash values
+    expect(djb2Hash('hello')).toBe(181380007);
+    expect(djb2Hash('world')).toBe(164394279);
+    expect(djb2Hash('hello world')).toBe(2616892229);
+    expect(djb2Hash('')).toBe(5381);
+  });
+
+  it('should handle case sensitivity', () => {
+    expect(djb2Hash('Hello')).not.toBe(djb2Hash('hello'));
+    expect(djb2Hash('WORLD')).not.toBe(djb2Hash('world'));
+  });
+});

package/src/{main.test.js → nano-hash.test.js}

@@ -1,22 +1,22 @@
-import {hashString} from '@alwatr/hash-string';
+import {nanoHash} from '@alwatr/hash-string';
 
 describe('hashString', () => {
   it('should generate hash for string inputs', () => {
-    const result = hashString('test', 'prefix-');
+    const result = nanoHash('test', 'prefix-');
     expect(typeof result).toBe('string');
     expect(result.startsWith('prefix-')).toBe(true);
     expect(result).not.toBe('prefix-test');
   });
 
   it('should generate hash for numeric inputs', () => {
-    const result = hashString(12345, 'num-');
+    const result = nanoHash(12345, 'num-');
     expect(typeof result).toBe('string');
     expect(result.startsWith('num-')).toBe(true);
   });
 
   it('should return different hashes for different inputs', () => {
-    const hash1 = hashString('test1', 'p-');
-    const hash2 = hashString('test2', 'p-');
+    const hash1 = nanoHash('test1', 'p-');
+    const hash2 = nanoHash('test2', 'p-');
     expect(hash1).not.toBe(hash2);
   });
 
@@ -24,7 +24,7 @@ describe('hashString', () => {
     const prefixes = ['a-', 'test-', 'hash_', '123-'];
 
     prefixes.forEach((prefix) => {
-      const result = hashString('sameInput', prefix);
+      const result = nanoHash('sameInput', prefix);
       expect(result.startsWith(prefix)).toBe(true);
     });
   });
@@ -33,9 +33,9 @@ describe('hashString', () => {
     const input = 'repeatTest';
     const prefix = 'r-';
 
-    const hash1 = hashString(input, prefix, 1);
-    const hash2 = hashString(input, prefix, 2);
-    const hash3 = hashString(input, prefix, 3);
+    const hash1 = nanoHash(input, prefix, 1);
+    const hash2 = nanoHash(input, prefix, 2);
+    const hash3 = nanoHash(input, prefix, 3);
 
     expect(hash1).not.toBe(hash2);
     expect(hash2).not.toBe(hash3);
@@ -43,14 +43,14 @@ describe('hashString', () => {
   });
 
   it('should handle empty strings', () => {
-    const result = hashString('', 'empty-');
+    const result = nanoHash('', 'empty-');
     expect(typeof result).toBe('string');
     expect(result.startsWith('empty-')).toBe(true);
     expect(result.length).toBeGreaterThan('empty-'.length);
   });
 
   it('should handle special characters', () => {
-    const result = hashString('!@#$%^&*()', 'special-');
+    const result = nanoHash('!@#$%^&*()', 'special-');
     expect(typeof result).toBe('string');
     expect(result.startsWith('special-')).toBe(true);
   });
@@ -59,15 +59,15 @@ describe('hashString', () => {
     const input = 'consistencyTest';
     const prefix = 'c-';
 
-    const hash1 = hashString(input, prefix);
-    const hash2 = hashString(input, prefix);
+    const hash1 = nanoHash(input, prefix);
+    const hash2 = nanoHash(input, prefix);
 
     expect(hash1).toBe(hash2);
   });
 
   it('should handle long strings', () => {
     const longString = 'a'.repeat(1000);
-    const result = hashString(longString, 'long-');
+    const result = nanoHash(longString, 'long-');
 
     expect(typeof result).toBe('string');
     expect(result.startsWith('long-')).toBe(true);
@@ -75,19 +75,27 @@ describe('hashString', () => {
 
   it('should handle Unicode characters', () => {
     const unicodeString = '😀🌍🚀';
-    const result = hashString(unicodeString, 'unicode-');
+    const result = nanoHash(unicodeString, 'unicode-');
 
     expect(typeof result).toBe('string');
     expect(result.startsWith('unicode-')).toBe(true);
   });
 
-  it('should default to repeat value of 3 when not specified', () => {
+  it('should default to repeat value of 1 when not specified', () => {
     const input = 'defaultRepeat';
     const prefix = 'd-';
 
-    const defaultResult = hashString(input, prefix);
-    const explicitResult = hashString(input, prefix, 3);
+    const defaultResult = nanoHash(input, prefix);
+    const explicitResult = nanoHash(input, prefix, 1);
 
     expect(defaultResult).toBe(explicitResult);
   });
+
+  it('should algorithm be deterministic', () => {
+    const input = 'Ali@MD_65';
+    const prefix = 'p-';
+    const expectedHash = 'p-dm3wzfp6jiud';
+    const hash = nanoHash(input, prefix, 3);
+    expect(hash).toBe(expectedHash);
+  });
 });