Published v1.0.0

.gitignore

@@ -0,0 +1,4 @@
+*.sw[op]
+dist
+node_modules
+.node-xml*

.husky/pre-commit

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+npx pretty-quick --staged

.npmignore

@@ -0,0 +1,6 @@
+*.sw[op]
+.node-xml*
+tests
+tsconfig*
+.vimrc
+.prettierignore

.npmrc

@@ -0,0 +1 @@
+@wymp:registry=https://npm.pkg.github.com/wymp

.prettierignore

@@ -0,0 +1 @@
+*.md

.vimrc

@@ -0,0 +1,3 @@
+set tabstop=2
+set shiftwidth=2
+set expandtab

README.md

@@ -0,0 +1,113 @@
+Indexed Debouncer
+=======================================================================
+
+A class that can be instantiated as a global dependency and which can keep track of named debounces
+across various disparate execution calls. This was built specifically to address React component
+mount/unmount chaos, in which a "normal" debounce function wouldn't work because it is being
+instantiated as a new instance every execution.
+
+Note: Detailed library API docs are available in this repo at `/docs/index.html`.
+
+
+## Usage
+
+The primary export of this library is the [`Debouncer` class](classes/Debouncer.html).
+
+**Note: `Debouncer` has a default wait time of 15ms. This may be changed globally by passing a
+different default in the `Debouncer` constructor, or it may be changed per-invocation by passing a
+wait time as the last parameter of `bounce`.**
+
+To use, first create a global instance of `Debouncer`, then use the `bounce` method of that instance
+to debounce functions. Each invocation of `bounce` with a given name will return a new promise that
+resolves to either `canceled`, if that particular invocation was canceled, or the return value of
+the function if that instance ends up actually firing. (Any errors cause the promise to reject, as
+one might expect.)
+
+You may use this to selectively update state only for successfully debounced actions.
+
+For example:
+
+```ts
+import { Debouncer } from "@wymp/indexed-debouncer";
+import { useEffect, useState } from "react";
+
+const debouncer = new Debouncer();
+
+// React component
+const App = (p: { debouncer: Debouncer }) => {
+  const [status, setStatus] = useState<"init"|"ready">("init");
+
+  useEffect(() => {
+    debouncer
+      .bounce("init-app", () => console.log("do thing"), 20)
+      .then(result => {
+        if (result !== "canceled") {
+          setStatus("ready");
+        }
+      });
+  });
+
+  return <div>
+    <p>{status === "init" ? "Initializing" : "Ready!"}</p>
+  </div>
+}
+```
+
+If for some reason you'd like to use the raw `DebounceFunc`, you may do that as well:
+
+```ts
+import { DebounceFunc } from "@wymp/indexed-debouncer";
+
+const func = new DebounceFunc(30);
+
+const promises: Array<Promise<"canceled" | number>> = [
+  func.bounce(() => 1),
+  func.bounce(() => 2),
+  func.bounce(() => 3),
+  func.bounce(() => 4),
+];
+
+Promise.all(promises).then(console.log);
+
+// Outputs the following:
+//
+// [ "canceled", "canceled", "canceled", 4 ]
+//
+```
+
+
+### Advanced Types
+
+This library will work without any type parameters specified. However, there is a risk of using
+overlapping keys that can lead to unexpected results.
+
+To avoid this, you can pass a `Contract` type parameter to the `Debouncer` constructor. This will
+enforce that you may only use one of the specified keys on bounces, and that the function you pass
+must conform to the type specified for that key. For example:
+
+```ts
+type Contract = {
+  "init-app": { status: "init" | "loading" | "ready" };
+  "init-mod-1": { thing: unknown };
+  "init-mod-2": void;
+}
+const debouncer = new Debouncer<Contract>();
+```
+
+In the above example, you may ONLY call `bounce` on this instance with one of the three keys
+specified, and the function you pass to `bounce` _must_ return the type indicated for that key (or
+a promise returning that type). For example, the following would both throw a type error:
+
+```ts
+debouncer.bounce("init-app", () => true);
+debouncer.bounce("non-existent", () => ({ status: "ready" }));
+```
+
+
+## Development
+
+1. run `npm install`
+2. Make code changes
+3. run `npx tsc`
+4. Make logical, specific commits
+

docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

docs/assets/highlight.css

@@ -0,0 +1,92 @@
+:root {
+    --light-hl-0: #AF00DB;
+    --dark-hl-0: #C586C0;
+    --light-hl-1: #000000;
+    --dark-hl-1: #D4D4D4;
+    --light-hl-2: #001080;
+    --dark-hl-2: #9CDCFE;
+    --light-hl-3: #A31515;
+    --dark-hl-3: #CE9178;
+    --light-hl-4: #0000FF;
+    --dark-hl-4: #569CD6;
+    --light-hl-5: #0070C1;
+    --dark-hl-5: #4FC1FF;
+    --light-hl-6: #795E26;
+    --dark-hl-6: #DCDCAA;
+    --light-hl-7: #008000;
+    --dark-hl-7: #6A9955;
+    --light-hl-8: #267F99;
+    --dark-hl-8: #4EC9B0;
+    --light-hl-9: #098658;
+    --dark-hl-9: #B5CEA8;
+    --light-code-background: #FFFFFF;
+    --dark-code-background: #1E1E1E;
+}
+
+@media (prefers-color-scheme: light) { :root {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
+    --code-background: var(--light-code-background);
+} }
+
+@media (prefers-color-scheme: dark) { :root {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
+    --code-background: var(--dark-code-background);
+} }
+
+:root[data-theme='light'] {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
+    --code-background: var(--light-code-background);
+}
+
+:root[data-theme='dark'] {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
+    --code-background: var(--dark-code-background);
+}
+
+.hl-0 { color: var(--hl-0); }
+.hl-1 { color: var(--hl-1); }
+.hl-2 { color: var(--hl-2); }
+.hl-3 { color: var(--hl-3); }
+.hl-4 { color: var(--hl-4); }
+.hl-5 { color: var(--hl-5); }
+.hl-6 { color: var(--hl-6); }
+.hl-7 { color: var(--hl-7); }
+.hl-8 { color: var(--hl-8); }
+.hl-9 { color: var(--hl-9); }
+pre, code { background: var(--code-background); }