@e280/stz 0.2.10 → 0.2.12

package/README.md

@@ -111,10 +111,12 @@ await nap(900)
   // wait for 900 milliseconds
 ```
 
-### 🍏 MapG
-> extended js Map
+### 🍏 G Crew
+> extended js data types
 
-- many say it's *"The Deluxe Mapping Experience"*
+#### GMap
+> extended js Map
+- many are saying it's *"The Deluxe Mapping Experience"*
   ```ts
   import {MapG} from "@e280/stz"
 
@@ -134,13 +136,13 @@ await nap(900)
     // "rofl"
   ```
 
-### 🍏 SetG
+#### GSet
 > extended js Set
 - `new SetG<T>()`
 - `set.adds(item1, item2, item3)` — add multiple items without a for-loop
 - `set.deletes(item1, item2, item3)` — add multiple items without a for-loop
 
-### 🍏 WeakMapG
+#### GWeakMap
 > extended js WeakMap
 - `new WeakMapG<K, V>()`
 - `weakMap.require(key)` — returns value for key.. if missing, throw an error
@@ -218,15 +220,15 @@ fn()
 // coolAction is only called once here, other calls are redundant
 ```
 
-### 🍏 `repeat(fn)`
+### 🍏 `cycle(fn)`
 > execute a function over and over again, back to back
 
 ```ts
-import {repeat} from "@e280/stz"
+import {cycle} from "@e280/stz"
 
 let ticks = 0
 
-const stop = repeat(async() => {
+const stop = cycle(async() => {
 
   // use a nap to add a delay between each execution
   await nap(200)
@@ -244,78 +246,49 @@ stop()
 
 ## 🥨 stz data utilities
 
-### 🍏 Hex
-> convert to/from hexadecimal string format
-- `Hex.fromBytes(bytes)` — bytes to hex string
-- `Hex.toBytes(string)` — hex string to bytes
-- `Hex.random(32)` — generate random hex string (32 bytes)
-
-### 🍏 Base64
-> convert to/from base64 string format
-- `Base64.fromBytes(bytes)` — bytes to string
-- `Base64.toBytes(string)` — string to bytes
-- `Base64.random(32)` — generate random string (32 bytes)
-
-### 🍏 Base64url
-> convert to/from base64 string format
-- `Base64url.fromBytes(bytes)` — bytes to string
-- `Base64url.toBytes(string)` — string to bytes
-- `Base64url.random(32)` — generate random string (32 bytes)
-
-### 🍏 Base58
-> convert to/from base64 string format
-- `Base58.fromBytes(bytes)` — bytes to string
-- `Base58.toBytes(string)` — string to bytes
-- `Base58.random(32)` — generate random string (32 bytes)
-
-### 🍏 Txt
+### 🍏 txt
 > convert to/from utf8 string format
-- `Txt.fromBytes(bytes)` — bytes to string
-- `Txt.toBytes(string)` — string to bytes
+- `txt.fromBytes(bytes)` — bytes to string
+- `txt.toBytes(string)` — string to bytes
 
-### 🍏 Bytes
+### 🍏 bytes
 > utilities for dealing with Uint8Array
-- `Bytes.eq(bytesA, bytesB)` — check if two byte arrays are equal
-- `Bytes.random(32)` — generate crypto-random bytes
+- `bytes.eq(bytesA, bytesB)` — check if two byte arrays are equal
+- `bytes.random(32)` — generate crypto-random bytes
 
-### 🍏 BaseX
-> convert data into arbitrary data encodings
-- make a BaseX instance
-  ```ts
-  import {BaseX} from "@e280/stz"
+### 🍏 BaseX utilities
+> convert binary data to/from various encodings
 
-  const hex = new BaseX(BaseX.lexicons.hex)
-  ```
-- convert between strings and binary
-  ```ts
-  hex.toBytes("9960cd633a46acfe8307d8a400e842da0d930a75fb8188e0f5da264e4b6b4e5b")
-    // Uint8Array
+```ts
+import {hex, base58, base64} from "@e280/stz"
+```
 
-  hex.fromBytes(bytes)
-    // string
-  ```
-- you can also convert between strings and integers
-  ```ts
-  hex.fromInteger(Date.now())
-    // "197140ac804"
+#### hex
+> all BaseX utilities have these methods
+- `hex.fromBytes(u8array)` — encode bytes to string
+- `hex.toBytes(str)` — decode string to bytes
+- `hex.toInteger(string)` — decode string as js integer
+- `hex.fromInteger(n)` — encode js integer as a string
+- `hex.random(32)` — generate random encoded string (32 bytes)
+
+#### all BaseX utilities
+- `hex`
+- `base2`
+- `base36`
+- `base58`
+- `base62`
+- `base64`
+- `base64url`
+
+#### make a custom BaseX utility
+- you can provide a `lexicon` to produce your own BaseX codec
+    ```ts
+    const myHex = new BaseX({characters: "0123456789abcdef"})
+    ```
 
-  hex.toInteger(hex)
-    // 1748387940356
-  ```
-- available lexicons include
-	- base2
-	- hex
-	- base36
-	- base58
-	- base62
-	- base64 (with standard padding)
-	- base64url
-- you can make insanely compact timestamps like this:
+#### tiny timestamps
+- fun fact: you can make insanely compact timestamp strings like this:
   ```ts
-  import {BaseX} from "@e280/stz"
-
-  const base62 = new BaseX(BaseX.lexicons.base62)
-
   base62.fromInteger(Date.now() / 1000)
     // "1uK3au"
   ```
@@ -323,35 +296,31 @@ stop()
   - `1uK3au` base62 epoch seconds (6 chars)
   - *nice*
 
-
-
-<br/>
-
-### 🍏 Bytename
+### 🍏 bytename
 > friendly string encoding for binary data
 
 a bytename looks like `"midsen.picmyn.widrep.baclut dotreg.filtyp.nosnus.siptev"`. that's 16 bytes. each byte maps to a three-letter triplet
 
-the bytename parser (`Bytename.toBytes`) ignores all non-alphabetic characters. thus `midsen.picmyn`, `midsenpicmyn`, and `mid@sen$pic@myn` are all equal.
+the bytename parser (`bytename.toBytes`) ignores all non-alphabetic characters. thus `midsen.picmyn`, `midsenpicmyn`, and `mid@sen$pic@myn` are all equal.
 
 ```ts
-import {Bytename} from "@e280/stz"
+import {bytename} from "@e280/stz"
 ```
 - ```ts
-  Bytename.fromBytes(new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]))
+  bytename.fromBytes(new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]))
     // "ribmug.hilmun"
   ```
 - ```ts
-  Bytename.toBytes("ribmug.hilmun")
+  bytename.toBytes("ribmug.hilmun")
     // Uint8Array, 4 bytes
   ```
 - ```ts
-  const bytes = new Uint8Array([
+  const data = new Uint8Array([
     0xDE, 0xAD, 0xBE, 0xEF,
     0xDE, 0xAD, 0xBE, 0xEF,
   ])
 
-  Bytename.fromBytes(bytes, {
+  bytename.fromBytes(data, {
     groupSize: 2, // default is 4
     groupSeparator: " ",
     wordSeparator: ".",
@@ -359,6 +328,62 @@ import {Bytename} from "@e280/stz"
     // "ribmug.hilmun ribmug.hilmun"
   ```
 
+### 🍏 thumbprint
+> hybrid of bytename and base58 to make binary data more human-friendly
+- looks like `nodlyn.fasrep.habbud.ralwel.Avo7gFmdWMRHkwsD149mcaBoZdS69iXuJ`
+- the idea is that the first parts are in bytename format, so it's easy for humans to recognize
+- and the remaining data is shown in base58
+- `thumbprint.fromBytes(u8array)` — encode bytes to thumbprint string
+- `thumbprint.toBytes(thumbstring)` — decode thumbprint string to bytes
+- `thumbprint.fromHex(hexstring)` — convert a hex string into a thumbprint
+- `thumbprint.toHex(thumbstring)` — convert a thumbprint into a hex string
+
+### 🍏 toq
+> tar-like binary file format for efficiently packing multiple files together
+
+```ts
+import {toq, txt} from "@e280/stz"
+```
+
+#### data layout
+- 4 magic bytes `"TOQ\x01"`
+- for each file (little endian)
+  - `name length` 1 byte (u8)
+  - `name` x bytes (max 255 B)
+  - `data length` 4 bytes (u32)
+  - `data` x bytes (max 4 GB)
+
+#### toq pack/unpack
+- **toq.pack** — accepts any iterable of file entries
+    ```ts
+    const pack: Uint8Array = toq.pack([
+      ["hello.txt", txt.toBytes("hello world")],
+      ["deadbeef.data", new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF])],
+    ])
+    ```
+- **toq.is** — check if a file is a toq pack or not
+    ```ts
+    toq.is(pack) // true
+    ```
+- **toq.unpack** — generator fn yields file entries
+    ```ts
+    for (const [name, data] of toq.unpack(pack))
+      console.log(name, data.length)
+    ```
+
+#### toq works nice with maps
+- **pack a map of files**
+    ```ts
+    const files = new Map<string, Uint8Array>()
+    files.set("hello.txt", txt.toBytes("hello world"))
+    files.set("deadbeef.data", new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]))
+
+    const pack = toq.pack(files)
+    ```
+- **unpack into a new map**
+    ```ts
+    const files = new Map(toq.unpack(pack))
+    ```
 
 
 <br/><br/>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/stz",
-	"version": "0.2.10",
+	"version": "0.2.12",
 	"description": "everyday ts fns for everything",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -28,7 +28,7 @@
 	},
 	"devDependencies": {
 		"@e280/science": "^0.1.2",
-		"@types/node": "^24.6.2",
+		"@types/node": "^24.7.1",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.9.3"
 	},

package/s/data/base-x-codecs.ts

@@ -0,0 +1,11 @@
+
+import {BaseX} from "./base-x.js"
+
+export const hex = new BaseX(BaseX.lexicons.hex)
+export const base2 = new BaseX(BaseX.lexicons.base2)
+export const base36 = new BaseX(BaseX.lexicons.base36)
+export const base58 = new BaseX(BaseX.lexicons.base58)
+export const base62 = new BaseX(BaseX.lexicons.base62)
+export const base64 = new BaseX(BaseX.lexicons.base64)
+export const base64url = new BaseX(BaseX.lexicons.base64url)
+

package/s/data/base-x.ts

@@ -1,5 +1,5 @@
 
-import {Bytes} from "./bytes.js"
+import {bytes} from "./bytes.js"
 
 export type Lexicon = {
 	characters: string
@@ -164,7 +164,7 @@ export class BaseX {
 	}
 
 	random(count = 32) {
-		return this.fromBytes(Bytes.random(count))
+		return this.fromBytes(bytes.random(count))
 	}
 }
 

package/s/data/bytename/bytename.test.ts

@@ -1,34 +1,34 @@
 
-import {Bytes} from "../bytes.js"
-import {Bytename} from "./bytename.js"
+import {bytes} from "../bytes.js"
+import {bytename} from "./bytename.js"
 import {Science, test, expect} from "@e280/science"
 
 const deadbeef = new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF])
 
-function good(bytes: Uint8Array) {
-	expect(Bytes.eq(bytes, deadbeef)).ok()
+function good(b: Uint8Array) {
+	expect(bytes.eq(b, deadbeef)).ok()
 }
 
 export default Science.suite({
 	"bytes->string->bytes": test(async() => {
-		const text = Bytename.fromBytes(deadbeef)
+		const text = bytename.fromBytes(deadbeef)
 		expect(text).is("ribmug.hilmun")
-		good(Bytename.toBytes(text))
+		good(bytename.toBytes(text))
 	}),
 
 	"zero bytes": test(async() => {
-		const text = Bytename.fromBytes(new Uint8Array([]))
+		const text = bytename.fromBytes(new Uint8Array([]))
 		expect(text).is("")
 	}),
 
 	"one byte": test(async() => {
-		const text = Bytename.fromBytes(new Uint8Array([0x00]))
+		const text = bytename.fromBytes(new Uint8Array([0x00]))
 		expect(text).is("doz")
 	}),
 
 	"groupings": test(async() => {
 		const bytes = new Uint8Array([...deadbeef, ...deadbeef])
-		const text = Bytename.fromBytes(bytes, {
+		const text = bytename.fromBytes(bytes, {
 			groupSize: 2,
 			groupSeparator: " ",
 			wordSeparator: ".",
@@ -37,13 +37,13 @@ export default Science.suite({
 	}),
 
 	"wordsep": Science.suite({
-		"underscore": test(async() => good(Bytename.toBytes("ribmug_hilmun"))),
-		"uppercase": test(async() => good(Bytename.toBytes("RIBMUG_HILMUN"))),
-		"dots": test(async() => good(Bytename.toBytes("ribmug.hilmun"))),
-		"crushed": test(async() => good(Bytename.toBytes("ribmughilmun"))),
-		"space": test(async() => good(Bytename.toBytes("ribmug hilmun"))),
-		"spaces": test(async() => good(Bytename.toBytes("ribmug  hilmun"))),
-		"whitespace": test(async() => good(Bytename.toBytes("\n ribmug \n \t \n hilmun \n"))),
+		"underscore": test(async() => good(bytename.toBytes("ribmug_hilmun"))),
+		"uppercase": test(async() => good(bytename.toBytes("RIBMUG_HILMUN"))),
+		"dots": test(async() => good(bytename.toBytes("ribmug.hilmun"))),
+		"crushed": test(async() => good(bytename.toBytes("ribmughilmun"))),
+		"space": test(async() => good(bytename.toBytes("ribmug hilmun"))),
+		"spaces": test(async() => good(bytename.toBytes("ribmug  hilmun"))),
+		"whitespace": test(async() => good(bytename.toBytes("\n ribmug \n \t \n hilmun \n"))),
 	}),
 })
 

package/s/data/bytename/bytename.ts

@@ -1,6 +1,6 @@
 
-import {Hex} from "../hex.js"
-import {Bytes} from "../bytes.js"
+import {bytes} from "../bytes.js"
+import {hex} from "../base-x-codecs.js"
 import {prefixes} from "./utils/prefixes.js"
 import {suffixes} from "./utils/suffixes.js"
 
@@ -16,7 +16,7 @@ export type BytenameOptions = {
  *  - each byte maps to a three-letter triplet
  *  - all delimiters are just sugar, parser doesn't care
  */
-export const Bytename = {
+export const bytename = {
 	defaults: (<BytenameOptions>{
 		groupSize: 4,
 		wordSeparator: ".",
@@ -24,21 +24,21 @@ export const Bytename = {
 	}),
 
 	random(byteCount: number, options?: Partial<BytenameOptions>) {
-		const bytes = Bytes.random(byteCount)
-		return this.fromBytes(bytes, options)
+		const b = bytes.random(byteCount)
+		return this.fromBytes(b, options)
 	},
 
-	fromBytes(bytes: Uint8Array, options: Partial<BytenameOptions> = {}) {
+	fromBytes(b: Uint8Array, options: Partial<BytenameOptions> = {}) {
 		const {
-			groupSize = Bytename.defaults.groupSize,
-			wordSeparator = Bytename.defaults.wordSeparator,
-			groupSeparator = Bytename.defaults.groupSeparator,
+			groupSize = bytename.defaults.groupSize,
+			wordSeparator = bytename.defaults.wordSeparator,
+			groupSeparator = bytename.defaults.groupSeparator,
 		} = options
 
 		const words: string[] = []
 		let currentWord: string[] = []
 
-		bytes.forEach((byte, index) => {
+		b.forEach((byte, index) => {
 			const source = ((index % 2) === 0) ? prefixes : suffixes
 			currentWord.push(source[byte]!)
 			if (currentWord.length === 2) {
@@ -57,8 +57,8 @@ export const Bytename = {
 		return grouped.join(groupSeparator)
 	},
 
-	toBytes(bytename: string) {
-		const letters = bytename
+	toBytes(bname: string) {
+		const letters = bname
 			.toLowerCase()
 			.replace(/[^a-z]/g, "") // strip everything except letters
 
@@ -79,12 +79,15 @@ export const Bytename = {
 		}))
 	},
 
-	toHex(bytename: string) {
-		return Hex.fromBytes(Bytename.toBytes(bytename))
+	toHex(bname: string) {
+		return hex.fromBytes(bytename.toBytes(bname))
 	},
 
-	fromHex(hex: string, options?: Partial<BytenameOptions>) {
-		return Bytename.fromBytes(Hex.toBytes(hex), options)
+	fromHex(h: string, options?: Partial<BytenameOptions>) {
+		return bytename.fromBytes(hex.toBytes(h), options)
 	},
 }
 
+/** @deprecated renamed to `bytename` */
+export const Bytename = bytename
+

package/s/data/bytename/thumbprint.test.ts

@@ -1,53 +1,53 @@
 
 import {Science, test, expect} from "@e280/science"
-import {Hex} from "../hex.js"
-import {Bytes} from "../bytes.js"
-import {Thumbprint} from "./thumbprint.js"
+import {bytes} from "../bytes.js"
+import {hex} from "../base-x-codecs.js"
+import {thumbprint} from "./thumbprint.js"
 
 const sampleThumbprint = "nodlyn.fasrep.habbud.ralwel.Avo7gFmdWMRHkwsD149mcaBoZdS69iXuJ"
 const sampleHex = "88e8c3fad1028fcf6ce5ac491578850f4d833336feca03b608265501c3019d59"
-const sampleBytes = Hex.toBytes(sampleHex)
+const sampleBytes = hex.toBytes(sampleHex)
 
-function good(bytes: Uint8Array) {
-	expect(Bytes.eq(bytes, sampleBytes)).ok()
+function good(b: Uint8Array) {
+	expect(bytes.eq(b, sampleBytes)).ok()
 }
 
 export default Science.suite({
 	"bytes->string->bytes": test(async() => {
-		const text = Thumbprint.fromBytes(sampleBytes)
+		const text = thumbprint.fromBytes(sampleBytes)
 		expect(text).is(sampleThumbprint)
-		good(Thumbprint.toBytes(text))
+		good(thumbprint.toBytes(text))
 	}),
 
 	"zero bytes": test(async() => {
-		const text = Thumbprint.fromBytes(new Uint8Array([]))
+		const text = thumbprint.fromBytes(new Uint8Array([]))
 		expect(text).is("")
-		expect(Bytes.eq(Thumbprint.toBytes(text), new Uint8Array([]))).ok()
+		expect(bytes.eq(thumbprint.toBytes(text), new Uint8Array([]))).ok()
 	}),
 
 	"one byte": test(async() => {
-		const text = Thumbprint.fromBytes(new Uint8Array([0x00]))
+		const text = thumbprint.fromBytes(new Uint8Array([0x00]))
 		expect(text).is("doz")
-		expect(Bytes.eq(Thumbprint.toBytes(text), new Uint8Array([0x00]))).ok()
+		expect(bytes.eq(thumbprint.toBytes(text), new Uint8Array([0x00]))).ok()
 	}),
 
 	"partially": Science.suite({
-		"normal": test(async() => expect(Thumbprint.toBytes(sampleThumbprint).length).ok()),
-		"nothing": test(async() => expect(Thumbprint.toBytes("").length).is(0)),
-		"no-bulk": test(async() => expect(Thumbprint.toBytes("nodlyn.fasrep").length).ok()),
-		"one-byte": test(async() => expect(Thumbprint.toBytes("nod").length).is(1)),
-		"three-byte": test(async() => expect(Thumbprint.toBytes("nodlynfas").length).is(3)),
-		"one-byte-sigil": test(async() => expect(Thumbprint.toBytes("nod::39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k").length).ok()),
+		"normal": test(async() => expect(thumbprint.toBytes(sampleThumbprint).length).ok()),
+		"nothing": test(async() => expect(thumbprint.toBytes("").length).is(0)),
+		"no-bulk": test(async() => expect(thumbprint.toBytes("nodlyn.fasrep").length).ok()),
+		"one-byte": test(async() => expect(thumbprint.toBytes("nod").length).is(1)),
+		"three-byte": test(async() => expect(thumbprint.toBytes("nodlynfas").length).is(3)),
+		"one-byte-sigil": test(async() => expect(thumbprint.toBytes("nod::39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k").length).ok()),
 	}),
 
 	"tolerance": Science.suite({
-		"normal": test(async() => good(Thumbprint.toBytes("nodlyn.fasrep::39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
-		"coolio": test(async() => good(Thumbprint.toBytes("nodlyn.fasrep..39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
-		"spaces": test(async() => good(Thumbprint.toBytes("nodlyn fasrep 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
-		"dots": test(async() => good(Thumbprint.toBytes("nodlyn.fasrep.39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
-		"one-space": test(async() => good(Thumbprint.toBytes("nodlynfasrep 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
-		"one-newline": test(async() => good(Thumbprint.toBytes("nodlynfasrep\n39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
-		"whitespace": test(async() => good(Thumbprint.toBytes("\t\n nodlyn\n fasrep \n\n\t\n 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k\n\t"))),
+		"normal": test(async() => good(thumbprint.toBytes("nodlyn.fasrep::39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"coolio": test(async() => good(thumbprint.toBytes("nodlyn.fasrep..39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"spaces": test(async() => good(thumbprint.toBytes("nodlyn fasrep 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"dots": test(async() => good(thumbprint.toBytes("nodlyn.fasrep.39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"one-space": test(async() => good(thumbprint.toBytes("nodlynfasrep 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"one-newline": test(async() => good(thumbprint.toBytes("nodlynfasrep\n39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k"))),
+		"whitespace": test(async() => good(thumbprint.toBytes("\t\n nodlyn\n fasrep \n\n\t\n 39gfeGFAAnBzH5pkT7EdoETMUMAekG9h1iymk6k\n\t"))),
 	}),
 })