@e280/stz 0.0.0-30 → 0.0.0-32

package/README.md

@@ -1,38 +1,81 @@
 
 # `@e280/stz`
-standard library of environment-agnostic typescript functions we use basically everywhere
-- zero dependencies
+
+**stz** is e280's standard library of environment-agnostic typescript tools.
+
+it's our javascript toolkit.
+
+zero dependencies.
 
 <br/>
 
-## MapG
-### extended js map
-- `map.require`
-  ```ts
-  import {MapG} from "@e280/stz"
+## 🧰 STZ PRIMITIVES
+> cool concepts we use all over the place
 
-  const map = new MapG<number, string>([
-    [1, "hello"],
-    [2, "world"],
-  ])
+### 🍏 MapG
+> extended js map
+
+```ts
+import {MapG} from "@e280/stz"
 
-  // throws error if the value is undefined
+const map = new MapG<number, string>([
+  [1, "hello"],
+  [2, "world"],
+])
+```
+
+- `map.require(key)` — throws error if the value is undefined
+  ```ts
   const value = map.require(1)
+    // "hello"
   ```
-- `map.guarantee`
+- `map.guarantee(key, make)` — returns the value for `key`, but if undefined, run `make` to set the value
   ```ts
-  // if the value is undefined, the new value "rofl" is set and returned
   const value = map.guarantee(3, () => "rofl")
+    // "rofl"
   ```
 
-<br/>
+### 🍏 nap
+> sleep for some milliseconds
+
+```ts
+import {nap} from "@e280/stz"
+
+await nap(900)
+  // wait for 900 milliseconds
+```
+
+### 🍏 defer
+> defer the resolve/reject of a promise to the outside
+
+```ts
+import {defer} from "@e280/stz"
+
+const deferred = defer()
+```
+
+- resolve the deferred promise
+    ```ts
+    deferred.resolve()
+    ```
+- reject the deferred promise
+    ```ts
+    deferred.reject(new Error("fail"))
+    ```
+- await the promise
+    ```ts
+    await deferred.promise
+    ```
+
+### 🍏 `pub` and `sub`
+> ergonomic event emitters
+
+```ts
+import {pub, sub} from "@e280/stz"
+```
 
-## pub and sub
-### ergonomic event emitters
 - make a publisher fn
   ```ts
-  import {pub} from "@e280/stz"
-
   // create a pub fn
   const sendMessage = pub<[string]>()
 
@@ -44,8 +87,6 @@ standard library of environment-agnostic typescript functions we use basically e
   ```
 - make a subscriber fn *(see how it's just the reverse of pub?)*
   ```ts
-  import {sub} from "@e280/stz"
-
   // create a sub fn
   const onMessage = sub<[string]>()
 
@@ -81,10 +122,82 @@ standard library of environment-agnostic typescript functions we use basically e
 
 <br/>
 
-## Data utilities
-> codecs for representing data in different ways
+## 🧰 FN TOOLS
+> function-oriented tools
+
+### 🍏 `queue(fn)`
+> execute calls in sequence (not concurrent)
+
+```ts
+import {queue, nap} from "@e280/stz"
+
+const fn = queue(async() => nap(100))
+
+fn()
+fn()
+await fn() // waits for the previous calls (sequentially)
+```
+
+### 🍏 `once(fn)`
+> ensure a fn is only executed one time
+
+```ts
+import {once} from "@e280/stz"
+
+let count = 0
+const fn = once(() => count++)
+console.log(count) // 0
+
+fn()
+console.log(count) // 1
+
+fn()
+console.log(count) // 1
+```
+
+### 🍏 `deadline(100, fn)`
+> throws an error if the async function takes too long
+
+```ts
+import {deadline} from "@e280/stz"
+
+const fn = deadline(100, async() => {
+
+  // example deliberately takes too long
+  await nap(200)
+})
+
+await fn()
+  // DeadlineError: deadline exceeded (0.1 seconds)
+```
+
+### 🍏 `repeat(fn)`
+> execute a function over and over again, back to back
+
+```ts
+import {repeat} from "@e280/stz"
+
+let ticks = 0
+
+const stop = repeat(async() => {
+
+  // use a nap to add a delay between each execution
+  await nap(200)
+
+  ticks++
+})
+
+// stop repeating whenever you want
+stop()
+```
+
+<br/>
+
+## 🧰 DATA UTILITIES
+> transforming and representing binary data
 
-### BaseX
+### 🍏 BaseX
+> represent data in arbitrary encodings
 - make a BaseX instance
   ```ts
   import {BaseX} from "@e280/stz"
@@ -130,7 +243,7 @@ standard library of environment-agnostic typescript functions we use basically e
 
 <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
@@ -164,6 +277,8 @@ import {Bytename} from "@e280/stz"
 
 <br/>
 
+<br/>
+
 ## 💖 stz is made with open source love
 reward us with github stars  
 build with us at https://e280.org/ but only if you're cool  

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/stz",
-	"version": "0.0.0-30",
+	"version": "0.0.0-32",
 	"description": "everyday ts fns for everything",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",

package/s/deadline.ts

@@ -1,23 +1,21 @@
 
 export class DeadlineError extends Error {
 	name = this.constructor.name
-	constructor(public milliseconds: number, message: string) {
-		super(`${message}, timed out in ${(milliseconds / 1000).toFixed(1)} seconds`)
+	constructor(public milliseconds: number) {
+		super(`deadline exceeded (${(milliseconds / 1000).toFixed(1)} seconds)`)
 	}
 }
 
 /** set a deadline for a fn to do something, will reject with a `DeadlineError` if it takes too long */
-export function deadline<R>(milliseconds: number, message: string, fn: () => Promise<R>) {
+export function deadline<R>(milliseconds: number, fn: () => Promise<R>) {
 	if (milliseconds <= 0 || milliseconds === Infinity)
 		return fn()
 
 	return new Promise<R>((resolve, reject) => {
-
 		const id = setTimeout(
-			() => reject(new DeadlineError(milliseconds, message)),
+			() => reject(new DeadlineError(milliseconds)),
 			milliseconds,
 		)
-
 		fn()
 			.then(resolve)
 			.catch(reject)

package/x/deadline.d.ts

@@ -1,7 +1,7 @@
 export declare class DeadlineError extends Error {
     milliseconds: number;
     name: string;
-    constructor(milliseconds: number, message: string);
+    constructor(milliseconds: number);
 }
 /** set a deadline for a fn to do something, will reject with a `DeadlineError` if it takes too long */
-export declare function deadline<R>(milliseconds: number, message: string, fn: () => Promise<R>): Promise<R>;
+export declare function deadline<R>(milliseconds: number, fn: () => Promise<R>): Promise<R>;

package/x/deadline.js

@@ -1,17 +1,17 @@
 export class DeadlineError extends Error {
     milliseconds;
     name = this.constructor.name;
-    constructor(milliseconds, message) {
-        super(`${message}, timed out in ${(milliseconds / 1000).toFixed(1)} seconds`);
+    constructor(milliseconds) {
+        super(`deadline exceeded (${(milliseconds / 1000).toFixed(1)} seconds)`);
         this.milliseconds = milliseconds;
     }
 }
 /** set a deadline for a fn to do something, will reject with a `DeadlineError` if it takes too long */
-export function deadline(milliseconds, message, fn) {
+export function deadline(milliseconds, fn) {
     if (milliseconds <= 0 || milliseconds === Infinity)
         return fn();
     return new Promise((resolve, reject) => {
-        const id = setTimeout(() => reject(new DeadlineError(milliseconds, message)), milliseconds);
+        const id = setTimeout(() => reject(new DeadlineError(milliseconds)), milliseconds);
         fn()
             .then(resolve)
             .catch(reject)

package/x/deadline.js.map

@@ -1 +1 @@
-{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../s/deadline.ts"],"names":[],"mappings":"AACA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAEpB;IADnB,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IAC5B,YAAmB,YAAoB,EAAE,OAAe;QACvD,KAAK,CAAC,GAAG,OAAO,kBAAkB,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;QAD3D,iBAAY,GAAZ,YAAY,CAAQ;IAEvC,CAAC;CACD;AAED,uGAAuG;AACvG,MAAM,UAAU,QAAQ,CAAI,YAAoB,EAAE,OAAe,EAAE,EAAoB;IACtF,IAAI,YAAY,IAAI,CAAC,IAAI,YAAY,KAAK,QAAQ;QACjD,OAAO,EAAE,EAAE,CAAA;IAEZ,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAEzC,MAAM,EAAE,GAAG,UAAU,CACpB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,EACtD,YAAY,CACZ,CAAA;QAED,EAAE,EAAE;aACF,IAAI,CAAC,OAAO,CAAC;aACb,KAAK,CAAC,MAAM,CAAC;aACb,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAA;IAClC,CAAC,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../s/deadline.ts"],"names":[],"mappings":"AACA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAEpB;IADnB,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IAC5B,YAAmB,YAAoB;QACtC,KAAK,CAAC,sBAAsB,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;QADtD,iBAAY,GAAZ,YAAY,CAAQ;IAEvC,CAAC;CACD;AAED,uGAAuG;AACvG,MAAM,UAAU,QAAQ,CAAI,YAAoB,EAAE,EAAoB;IACrE,IAAI,YAAY,IAAI,CAAC,IAAI,YAAY,KAAK,QAAQ;QACjD,OAAO,EAAE,EAAE,CAAA;IAEZ,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACzC,MAAM,EAAE,GAAG,UAAU,CACpB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,YAAY,CAAC,CAAC,EAC7C,YAAY,CACZ,CAAA;QACD,EAAE,EAAE;aACF,IAAI,CAAC,OAAO,CAAC;aACb,KAAK,CAAC,MAAM,CAAC;aACb,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAA;IAClC,CAAC,CAAC,CAAA;AACH,CAAC"}