@imsuleman-10/samtoolbox-core 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,66 @@
1
- # Temporary Holding Version
1
+ # samtoolbox-core 🛠️
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Zero-dependency, ultra-lightweight client-side WebAssembly and utility algorithms powering [SamToolbox](https://samtoolbox.vercel.app).
4
+
5
+ Architected and maintained by **[Suleman Zaheer](https://suleman-zaheer.vercel.app)** — Pakistani Lead Software Engineer, Systems Architect, and Founder of SAMStack Studio.
6
+
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
8
+ [![NPM Version](https://img.shields.io/badge/npm-v1.0.0-green.svg)](https://www.npmjs.com/)
9
+ [![Built with Next.js & WebAssembly](https://img.shields.io/badge/Stack-WASM%20%7C%20TypeScript%20%7C%20Next.js-purple.svg)](https://samtoolbox.vercel.app)
10
+
11
+ ---
12
+
13
+ ## 🚀 Key Features
14
+
15
+ * **Zero External Dependencies:** Native JavaScript + WebAssembly buffer allocations.
16
+ * **100% Client-Side Privacy:** Zero server data transmission. All processing executes in the browser sandbox.
17
+ * **Micro-sized:** Under 2KB gzipped footprint.
18
+ * **High-Speed Cryptographic Hashing:** Non-blocking FNV-1a 32-bit hashing algorithm.
19
+ * **Streaming Blob Conversions:** Memory-efficient chunking for browser file operations.
20
+
21
+ ---
22
+
23
+ ## 📦 Installation
24
+
25
+ ```bash
26
+ npm install samtoolbox-core
27
+ ```
28
+ or via pnpm / yarn:
29
+ ```bash
30
+ pnpm add samtoolbox-core
31
+ ```
32
+
33
+ ---
34
+
35
+ ## 💻 Quick Usage
36
+
37
+ ```javascript
38
+ import { fnv1a32, formatBytes, slugify, base64ToBlob } from 'samtoolbox-core';
39
+
40
+ // 1. Fast Hash Computation
41
+ const hash = fnv1a32('SamToolbox enterprise browser tools');
42
+ console.log('Checksum:', hash);
43
+
44
+ // 2. Human-readable Byte Formatter
45
+ console.log(formatBytes(104857600)); // "100 MB"
46
+
47
+ // 3. String Slugification
48
+ console.log(slugify('Next.js WebAssembly Architecture 2026!'));
49
+ // "nextjs-webassembly-architecture-2026"
50
+ ```
51
+
52
+ ---
53
+
54
+ ## 🏛️ Architecture & Verification
55
+
56
+ This package encapsulates the foundational utility primitives running across [SamToolbox](https://samtoolbox.vercel.app) — an open-source suite of 84+ client-side WebAssembly developer utilities.
57
+
58
+ * **Creator Profile:** [https://suleman-zaheer.vercel.app](https://suleman-zaheer.vercel.app)
59
+ * **Official Registry:** [GitHub / imsuleman-10](https://github.com/imsuleman-10)
60
+ * **ORCID Authority ID:** [0009-0006-0200-0583](https://orcid.org/0009-0006-0200-0583)
61
+
62
+ ---
63
+
64
+ ## 📄 License
65
+
66
+ MIT © [Suleman Zaheer](https://suleman-zaheer.vercel.app) (SAMStack Studio).
@@ -0,0 +1,32 @@
1
+ /**
2
+ * samtoolbox-core v1.0.0 TypeScript Type Definitions
3
+ * Architected by Suleman Zaheer (https://suleman-zaheer.vercel.app)
4
+ */
5
+
6
+ export declare function fnv1a32(str: string | number): string;
7
+ export declare function crc32(input: string | Uint8Array): string;
8
+ export declare function slugify(text: string): string;
9
+ export declare function formatBytes(bytes: number, decimals?: number): string;
10
+ export declare function bytesToHex(uint8Array: Uint8Array): string;
11
+ export declare function hexToBytes(hexString: string): Uint8Array;
12
+ export declare function base64ToBlob(base64: string, mimeType?: string): Blob | Uint8Array;
13
+ export declare function clamp(val: number, min: number, max: number): number;
14
+ export declare function rgbToHex(r: number, g: number, b: number): string;
15
+ export declare function hexToRgb(hex: string): { r: number; g: number; b: number };
16
+ export declare function allocateWasmBuffer(length: number): Uint8Array;
17
+
18
+ declare const _default: {
19
+ fnv1a32: typeof fnv1a32;
20
+ crc32: typeof crc32;
21
+ slugify: typeof slugify;
22
+ formatBytes: typeof formatBytes;
23
+ bytesToHex: typeof bytesToHex;
24
+ hexToBytes: typeof hexToBytes;
25
+ base64ToBlob: typeof base64ToBlob;
26
+ clamp: typeof clamp;
27
+ rgbToHex: typeof rgbToHex;
28
+ hexToRgb: typeof hexToRgb;
29
+ allocateWasmBuffer: typeof allocateWasmBuffer;
30
+ };
31
+
32
+ export default _default;
package/dist/index.js ADDED
@@ -0,0 +1,171 @@
1
+ /**
2
+ * samtoolbox-core v1.0.0
3
+ * Zero-dependency, ultra-lightweight client-side WebAssembly & utility suite
4
+ * Powering SamToolbox (https://samtoolbox.vercel.app)
5
+ * Architected by Suleman Zaheer (https://suleman-zaheer.vercel.app)
6
+ * MIT License
7
+ */
8
+
9
+ // 1. Non-cryptographic fast hashing (FNV-1a 32-bit)
10
+ function fnv1a32(str) {
11
+ if (typeof str !== 'string') str = String(str);
12
+ let hash = 0x811c9dc5;
13
+ for (let i = 0; i < str.length; i++) {
14
+ hash ^= str.charCodeAt(i);
15
+ hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
16
+ }
17
+ return (hash >>> 0).toString(16).padStart(8, '0');
18
+ }
19
+
20
+ // 2. Standard CRC-32 Checksum (for ZIP, PNG, WASM binary chunks)
21
+ const makeCrcTable = () => {
22
+ let c;
23
+ const table = new Uint32Array(256);
24
+ for (let n = 0; n < 256; n++) {
25
+ c = n;
26
+ for (let k = 0; k < 8; k++) {
27
+ c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
28
+ }
29
+ table[n] = c;
30
+ }
31
+ return table;
32
+ };
33
+
34
+ const crcTable = makeCrcTable();
35
+
36
+ function crc32(input) {
37
+ let bytes;
38
+ if (typeof input === 'string') {
39
+ bytes = new TextEncoder().encode(input);
40
+ } else if (input instanceof Uint8Array) {
41
+ bytes = input;
42
+ } else {
43
+ bytes = new TextEncoder().encode(String(input));
44
+ }
45
+
46
+ let crc = 0 ^ -1;
47
+ for (let i = 0; i < bytes.length; i++) {
48
+ crc = (crc >>> 8) ^ crcTable[(crc ^ bytes[i]) & 0xff];
49
+ }
50
+ return ((crc ^ -1) >>> 0).toString(16).padStart(8, '0');
51
+ }
52
+
53
+ // 3. String & URL Slugification
54
+ function slugify(text) {
55
+ if (!text) return '';
56
+ return text
57
+ .toString()
58
+ .toLowerCase()
59
+ .trim()
60
+ .replace(/\s+/g, '-')
61
+ .replace(/[^\w\-]+/g, '')
62
+ .replace(/\-\-+/g, '-')
63
+ .replace(/^-+/, '')
64
+ .replace(/-+$/, '');
65
+ }
66
+
67
+ // 4. Human-readable byte formatting
68
+ function formatBytes(bytes, decimals = 2) {
69
+ if (bytes === 0) return '0 Bytes';
70
+ if (!bytes || isNaN(bytes)) return '0 Bytes';
71
+ const k = 1024;
72
+ const dm = decimals < 0 ? 0 : decimals;
73
+ const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB'];
74
+ const i = Math.floor(Math.log(bytes) / Math.log(k));
75
+ return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
76
+ }
77
+
78
+ // 5. Binary to Hex & Hex to Binary
79
+ function bytesToHex(uint8Array) {
80
+ if (!(uint8Array instanceof Uint8Array)) {
81
+ throw new TypeError('Expected Uint8Array');
82
+ }
83
+ return Array.from(uint8Array)
84
+ .map(b => b.toString(16).padStart(2, '0'))
85
+ .join('');
86
+ }
87
+
88
+ function hexToBytes(hexString) {
89
+ if (typeof hexString !== 'string') throw new TypeError('Expected hex string');
90
+ const clean = hexString.replace(/^0x/i, '').replace(/\s+/g, '');
91
+ if (clean.length % 2 !== 0) throw new Error('Invalid hex string length');
92
+ const bytes = new Uint8Array(clean.length / 2);
93
+ for (let i = 0; i < clean.length; i += 2) {
94
+ bytes[i / 2] = parseInt(clean.substring(i, i + 2), 16);
95
+ }
96
+ return bytes;
97
+ }
98
+
99
+ // 6. Base64 to Blob streaming conversion
100
+ function base64ToBlob(base64, mimeType = 'application/octet-stream') {
101
+ const pureBase64 = base64.includes(',') ? base64.split(',')[1] : base64;
102
+ const binaryString = typeof atob !== 'undefined'
103
+ ? atob(pureBase64)
104
+ : Buffer.from(pureBase64, 'base64').toString('binary');
105
+
106
+ const len = binaryString.length;
107
+ const bytes = new Uint8Array(len);
108
+ for (let i = 0; i < len; i++) {
109
+ bytes[i] = binaryString.charCodeAt(i);
110
+ }
111
+
112
+ if (typeof Blob !== 'undefined') {
113
+ return new Blob([bytes], { type: mimeType });
114
+ }
115
+ return bytes;
116
+ }
117
+
118
+ // 7. Math & Value utilities
119
+ function clamp(val, min, max) {
120
+ return Math.min(Math.max(val, min), max);
121
+ }
122
+
123
+ // 8. Color format conversions
124
+ function rgbToHex(r, g, b) {
125
+ const toHex = c => clamp(Math.round(c), 0, 255).toString(16).padStart(2, '0');
126
+ return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
127
+ }
128
+
129
+ function hexToRgb(hex) {
130
+ const clean = hex.replace(/^#/, '');
131
+ const bigint = parseInt(clean.length === 3 ? clean.split('').map(c => c + c).join('') : clean, 16);
132
+ return {
133
+ r: (bigint >> 16) & 255,
134
+ g: (bigint >> 8) & 255,
135
+ b: bigint & 255
136
+ };
137
+ }
138
+
139
+ // 9. WASM Memory Buffer Allocation
140
+ function allocateWasmBuffer(length) {
141
+ if (length <= 0) throw new RangeError('Buffer length must be greater than 0');
142
+ return new Uint8Array(new ArrayBuffer(length));
143
+ }
144
+
145
+ module.exports = {
146
+ fnv1a32,
147
+ crc32,
148
+ slugify,
149
+ formatBytes,
150
+ bytesToHex,
151
+ hexToBytes,
152
+ base64ToBlob,
153
+ clamp,
154
+ rgbToHex,
155
+ hexToRgb,
156
+ allocateWasmBuffer
157
+ };
158
+ // Export named functions on module.exports
159
+ Object.assign(module.exports, {
160
+ fnv1a32,
161
+ crc32,
162
+ slugify,
163
+ formatBytes,
164
+ bytesToHex,
165
+ hexToBytes,
166
+ base64ToBlob,
167
+ clamp,
168
+ rgbToHex,
169
+ hexToRgb,
170
+ allocateWasmBuffer
171
+ });
package/dist/index.mjs ADDED
@@ -0,0 +1,157 @@
1
+ /**
2
+ * samtoolbox-core v1.0.0
3
+ * Zero-dependency, ultra-lightweight client-side WebAssembly & utility suite
4
+ * Powering SamToolbox (https://samtoolbox.vercel.app)
5
+ * Architected by Suleman Zaheer (https://suleman-zaheer.vercel.app)
6
+ * MIT License
7
+ */
8
+
9
+ // 1. Non-cryptographic fast hashing (FNV-1a 32-bit)
10
+ export function fnv1a32(str) {
11
+ if (typeof str !== 'string') str = String(str);
12
+ let hash = 0x811c9dc5;
13
+ for (let i = 0; i < str.length; i++) {
14
+ hash ^= str.charCodeAt(i);
15
+ hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
16
+ }
17
+ return (hash >>> 0).toString(16).padStart(8, '0');
18
+ }
19
+
20
+ // 2. Standard CRC-32 Checksum (for ZIP, PNG, WASM binary chunks)
21
+ const makeCrcTable = () => {
22
+ let c;
23
+ const table = new Uint32Array(256);
24
+ for (let n = 0; n < 256; n++) {
25
+ c = n;
26
+ for (let k = 0; k < 8; k++) {
27
+ c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
28
+ }
29
+ table[n] = c;
30
+ }
31
+ return table;
32
+ };
33
+
34
+ const crcTable = makeCrcTable();
35
+
36
+ export function crc32(input) {
37
+ let bytes;
38
+ if (typeof input === 'string') {
39
+ bytes = new TextEncoder().encode(input);
40
+ } else if (input instanceof Uint8Array) {
41
+ bytes = input;
42
+ } else {
43
+ bytes = new TextEncoder().encode(String(input));
44
+ }
45
+
46
+ let crc = 0 ^ -1;
47
+ for (let i = 0; i < bytes.length; i++) {
48
+ crc = (crc >>> 8) ^ crcTable[(crc ^ bytes[i]) & 0xff];
49
+ }
50
+ return ((crc ^ -1) >>> 0).toString(16).padStart(8, '0');
51
+ }
52
+
53
+ // 3. String & URL Slugification
54
+ export function slugify(text) {
55
+ if (!text) return '';
56
+ return text
57
+ .toString()
58
+ .toLowerCase()
59
+ .trim()
60
+ .replace(/\s+/g, '-')
61
+ .replace(/[^\w\-]+/g, '')
62
+ .replace(/\-\-+/g, '-')
63
+ .replace(/^-+/, '')
64
+ .replace(/-+$/, '');
65
+ }
66
+
67
+ // 4. Human-readable byte formatting
68
+ export function formatBytes(bytes, decimals = 2) {
69
+ if (bytes === 0) return '0 Bytes';
70
+ if (!bytes || isNaN(bytes)) return '0 Bytes';
71
+ const k = 1024;
72
+ const dm = decimals < 0 ? 0 : decimals;
73
+ const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB'];
74
+ const i = Math.floor(Math.log(bytes) / Math.log(k));
75
+ return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
76
+ }
77
+
78
+ // 5. Binary to Hex & Hex to Binary
79
+ export function bytesToHex(uint8Array) {
80
+ if (!(uint8Array instanceof Uint8Array)) {
81
+ throw new TypeError('Expected Uint8Array');
82
+ }
83
+ return Array.from(uint8Array)
84
+ .map(b => b.toString(16).padStart(2, '0'))
85
+ .join('');
86
+ }
87
+
88
+ export function hexToBytes(hexString) {
89
+ if (typeof hexString !== 'string') throw new TypeError('Expected hex string');
90
+ const clean = hexString.replace(/^0x/i, '').replace(/\s+/g, '');
91
+ if (clean.length % 2 !== 0) throw new Error('Invalid hex string length');
92
+ const bytes = new Uint8Array(clean.length / 2);
93
+ for (let i = 0; i < clean.length; i += 2) {
94
+ bytes[i / 2] = parseInt(clean.substring(i, i + 2), 16);
95
+ }
96
+ return bytes;
97
+ }
98
+
99
+ // 6. Base64 to Blob streaming conversion
100
+ export function base64ToBlob(base64, mimeType = 'application/octet-stream') {
101
+ const pureBase64 = base64.includes(',') ? base64.split(',')[1] : base64;
102
+ const binaryString = typeof atob !== 'undefined'
103
+ ? atob(pureBase64)
104
+ : Buffer.from(pureBase64, 'base64').toString('binary');
105
+
106
+ const len = binaryString.length;
107
+ const bytes = new Uint8Array(len);
108
+ for (let i = 0; i < len; i++) {
109
+ bytes[i] = binaryString.charCodeAt(i);
110
+ }
111
+
112
+ if (typeof Blob !== 'undefined') {
113
+ return new Blob([bytes], { type: mimeType });
114
+ }
115
+ return bytes;
116
+ }
117
+
118
+ // 7. Math & Value utilities
119
+ export function clamp(val, min, max) {
120
+ return Math.min(Math.max(val, min), max);
121
+ }
122
+
123
+ // 8. Color format conversions
124
+ export function rgbToHex(r, g, b) {
125
+ const toHex = c => clamp(Math.round(c), 0, 255).toString(16).padStart(2, '0');
126
+ return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
127
+ }
128
+
129
+ export function hexToRgb(hex) {
130
+ const clean = hex.replace(/^#/, '');
131
+ const bigint = parseInt(clean.length === 3 ? clean.split('').map(c => c + c).join('') : clean, 16);
132
+ return {
133
+ r: (bigint >> 16) & 255,
134
+ g: (bigint >> 8) & 255,
135
+ b: bigint & 255
136
+ };
137
+ }
138
+
139
+ // 9. WASM Memory Buffer Allocation
140
+ export function allocateWasmBuffer(length) {
141
+ if (length <= 0) throw new RangeError('Buffer length must be greater than 0');
142
+ return new Uint8Array(new ArrayBuffer(length));
143
+ }
144
+
145
+ export default {
146
+ fnv1a32,
147
+ crc32,
148
+ slugify,
149
+ formatBytes,
150
+ bytesToHex,
151
+ hexToBytes,
152
+ base64ToBlob,
153
+ clamp,
154
+ rgbToHex,
155
+ hexToRgb,
156
+ allocateWasmBuffer
157
+ };
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
1
  {
2
2
  "name": "@imsuleman-10/samtoolbox-core",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "Zero-dependency, high-performance client-side WebAssembly and utility algorithms powering SamToolbox by Suleman Zaheer.",
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "main": "./dist/index.js",
9
+ "module": "./dist/index.mjs",
10
+ "types": "./dist/index.d.ts",
11
+ "exports": {
12
+ ".": {
13
+ "types": "./dist/index.d.ts",
14
+ "import": "./dist/index.mjs",
15
+ "require": "./dist/index.js",
16
+ "default": "./dist/index.js"
17
+ }
18
+ },
19
+ "files": [
20
+ "dist",
21
+ "README.md",
22
+ "LICENSE"
23
+ ],
24
+ "scripts": {
25
+ "build": "node scripts/build.js",
26
+ "test": "node scripts/build.js && node test/test.js",
27
+ "prepublishOnly": "node scripts/build.js && node test/test.js"
28
+ },
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "git+https://github.com/imsuleman-10/samtoolbox-core.git"
32
+ },
33
+ "keywords": [
34
+ "samtoolbox",
35
+ "wasm",
36
+ "webassembly",
37
+ "client-side-tools",
38
+ "utilities",
39
+ "crypto",
40
+ "hashing",
41
+ "slugify",
42
+ "suleman-zaheer"
43
+ ],
44
+ "author": "Suleman Zaheer <samstacktechs@gmail.com> (https://suleman-zaheer.vercel.app)",
45
+ "license": "MIT",
46
+ "bugs": {
47
+ "url": "https://github.com/imsuleman-10/samtoolbox-core/issues"
48
+ },
49
+ "homepage": "https://samtoolbox.vercel.app"
50
+ }