@tomorrowevening/theatre-dataverse 1.0.0

package/dist/prism/prism.d.ts

@@ -0,0 +1,175 @@
+import type { $IntentionalAny, VoidFn } from '../types';
+import type { Prism } from './Interface';
+type IRef<T> = {
+    current: T;
+};
+/**
+ * Just like React's `useRef()`, `prism.ref()` allows us to create a prism that holds a reference to some value.
+ * The only difference is that `prism.ref()` requires a key to be passed into it, whlie `useRef()` doesn't.
+ * This means that we can call `prism.ref()` in any order, and we can call it multiple times with the same key.
+ * @param key - The key for the ref. Should be unique inside of the prism.
+ * @param initialValue - The initial value for the ref.
+ * @returns `{current: V}` - The ref object.
+ *
+ * Note that the ref object will always return its initial value if the prism is cold. It'll only record
+ * its current value if the prism is hot (and will forget again if the prism goes cold again).
+ *
+ * @example
+ * ```ts
+ * const pr = prism(() => {
+ *   const ref1 = prism.ref("ref1", 0)
+ *   console.log(ref1.current) // will print 0, and if the prism is hot, it'll print the current value
+ *   ref1.current++ // changing the current value of the ref
+ * })
+ * ```
+ */
+declare function ref<T>(key: string, initialValue: T): IRef<T>;
+/**
+ * An effect hook, similar to React's `useEffect()`, but is not sensitive to call order by using `key`.
+ *
+ * @param key - the key for the effect. Should be uniqe inside of the prism.
+ * @param cb - the callback function. Requires returning a cleanup function.
+ * @param deps - the dependency array
+ */
+declare function effect(key: string, cb: () => () => void, deps?: unknown[]): void;
+/**
+ * `prism.memo()` works just like React's `useMemo()` hook. It's a way to cache the result of a function call.
+ * The only difference is that `prism.memo()` requires a key to be passed into it, whlie `useMemo()` doesn't.
+ * This means that we can call `prism.memo()` in any order, and we can call it multiple times with the same key.
+ *
+ * @param key - The key for the memo. Should be unique inside of the prism
+ * @param fn - The function to memoize
+ * @param deps - The dependency array. Provide `[]` if you want to the value to be memoized only once and never re-calculated.
+ * @returns The result of the function call
+ *
+ * @example
+ * ```ts
+ * const pr = prism(() => {
+ *  const memoizedReturnValueOfExpensiveFn = prism.memo("memo1", expensiveFn, [])
+ * })
+ * ```
+ */
+declare function memo<T>(key: string, fn: () => T, deps: undefined | $IntentionalAny[] | ReadonlyArray<$IntentionalAny>): T;
+/**
+ * A state hook, similar to react's `useState()`.
+ *
+ * @param key - the key for the state
+ * @param initialValue - the initial value
+ * @returns [currentState, setState]
+ *
+ * @example
+ * ```ts
+ * import {prism} from 'dataverse'
+ *
+ * // This prism holds the current mouse position and updates when the mouse moves
+ * const mousePositionD = prism(() => {
+ *   const [pos, setPos] = prism.state<[x: number, y: number]>('pos', [0, 0])
+ *
+ *   prism.effect(
+ *     'setupListeners',
+ *     () => {
+ *       const handleMouseMove = (e: MouseEvent) => {
+ *         setPos([e.screenX, e.screenY])
+ *       }
+ *       document.addEventListener('mousemove', handleMouseMove)
+ *
+ *       return () => {
+ *         document.removeEventListener('mousemove', handleMouseMove)
+ *       }
+ *     },
+ *     [],
+ *   )
+ *
+ *   return pos
+ * })
+ * ```
+ */
+declare function state<T>(key: string, initialValue: T): [T, (val: T) => void];
+/**
+ * This is useful to make sure your code is running inside a `prism()` call.
+ *
+ * @example
+ * ```ts
+ * import {prism} from '@tomorrowevening/theatre-dataverse'
+ *
+ * function onlyUsefulInAPrism() {
+ *   prism.ensurePrism()
+ * }
+ *
+ * prism(() => {
+ *   onlyUsefulInAPrism() // will run fine
+ * })
+ *
+ * setTimeout(() => {
+ *   onlyUsefulInAPrism() // throws an error
+ *   console.log('This will never get logged')
+ * }, 0)
+ * ```
+ */
+declare function ensurePrism(): void;
+declare function scope<T>(key: string, fn: () => T): T;
+/**
+ * Just an alias for `prism.memo(key, () => prism(fn), deps).getValue()`. It creates a new prism, memoizes it, and returns the value.
+ * `prism.sub()` is useful when you want to divide your prism into smaller prisms, each of which
+ * would _only_ recalculate when _certain_ dependencies change. In other words, it's an optimization tool.
+ *
+ * @param key - The key for the memo. Should be unique inside of the prism
+ * @param fn - The function to run inside the prism
+ * @param deps - The dependency array. Provide `[]` if you want to the value to be memoized only once and never re-calculated.
+ * @returns The value of the inner prism
+ */
+declare function sub<T>(key: string, fn: () => T, deps: undefined | $IntentionalAny[]): T;
+/**
+ * @returns true if the current function is running inside a `prism()` call.
+ */
+declare function inPrism(): boolean;
+/**
+ * `prism.source()`  allow a prism to react to changes in some external source (other than other prisms).
+ * For example, `Atom.pointerToPrism()` uses `prism.source()` to create a prism that reacts to changes in the atom's value.
+ 
+ * @param subscribe - The prism will call this function as soon as the prism goes hot. This function should return an unsubscribe function function which the prism will call when it goes cold.
+ * @param getValue - A function that returns the current value of the external source.
+ * @returns The current value of the source
+ *
+ * Example:
+ * ```ts
+ * function prismFromInputElement(input: HTMLInputElement): Prism<string> {
+ *   function listen(cb: (value: string) => void) {
+ *     const listener = () => {
+ *       cb(input.value)
+ *     }
+ *     input.addEventListener('input', listener)
+ *     return () => {
+ *       input.removeEventListener('input', listener)
+ *     }
+ *   }
+ *
+ *   function get() {
+ *     return input.value
+ *   }
+ *   return prism(() => prism.source(listen, get))
+ * }
+ * ```
+ */
+declare function source<V>(subscribe: (fn: (val: V) => void) => VoidFn, getValue: () => V): V;
+type IPrismFn = {
+    <T>(fn: () => T): Prism<T>;
+    ref: typeof ref;
+    effect: typeof effect;
+    memo: typeof memo;
+    ensurePrism: typeof ensurePrism;
+    state: typeof state;
+    scope: typeof scope;
+    sub: typeof sub;
+    inPrism: typeof inPrism;
+    source: typeof source;
+};
+/**
+ * Creates a prism from the passed function that adds all prisms referenced
+ * in it as dependencies, and reruns the function when these change.
+ *
+ * @param fn - The function to rerun when the prisms referenced in it change.
+ */
+declare const prism: IPrismFn;
+export default prism;
+//# sourceMappingURL=prism.d.ts.map

package/dist/prism/prism.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prism.d.ts","sourceRoot":"","sources":["../../src/prism/prism.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,eAAe,EAAE,MAAM,EAAC,MAAM,UAAU,CAAA;AAErD,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,aAAa,CAAA;AAmiBtC,KAAK,IAAI,CAAC,CAAC,IAAI;IACb,OAAO,EAAE,CAAC,CAAA;CACX,CAAA;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAOrD;AAED;;;;;;GAMG;AACH,iBAAS,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAOzE;AAoBD;;;;;;;;;;;;;;;;GAgBG;AACH,iBAAS,IAAI,CAAC,CAAC,EACb,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,CAAC,EACX,IAAI,EAAE,SAAS,GAAG,eAAe,EAAE,GAAG,aAAa,CAAC,eAAe,CAAC,GACnE,CAAC,CAOH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,iBAAS,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,CAOrE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iBAAS,WAAW,IAAI,IAAI,CAK3B;AAED,iBAAS,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAU7C;AAED;;;;;;;;;GASG;AACH,iBAAS,GAAG,CAAC,CAAC,EACZ,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,CAAC,EACX,IAAI,EAAE,SAAS,GAAG,eAAe,EAAE,GAClC,CAAC,CAEH;AAED;;GAEG;AACH,iBAAS,OAAO,IAAI,OAAO,CAE1B;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iBAAS,MAAM,CAAC,CAAC,EACf,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,EAC3C,QAAQ,EAAE,MAAM,CAAC,GAChB,CAAC,CAOH;AAED,KAAK,QAAQ,GAAG;IACd,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IAC1B,GAAG,EAAE,OAAO,GAAG,CAAA;IACf,MAAM,EAAE,OAAO,MAAM,CAAA;IACrB,IAAI,EAAE,OAAO,IAAI,CAAA;IACjB,WAAW,EAAE,OAAO,WAAW,CAAA;IAC/B,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,GAAG,EAAE,OAAO,GAAG,CAAA;IACf,OAAO,EAAE,OAAO,OAAO,CAAA;IACvB,MAAM,EAAE,OAAO,MAAM,CAAA;CACtB,CAAA;AAED;;;;;GAKG;AACH,QAAA,MAAM,KAAK,EAAE,QAEZ,CAAA;AAyDD,eAAe,KAAK,CAAA"}

package/dist/setupTestEnv.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setupTestEnv.d.ts.map

package/dist/setupTestEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupTestEnv.d.ts","sourceRoot":"","sources":["../src/setupTestEnv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAA"}

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.36.4"
+    }
+  ]
+}

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+/** For `any`s that aren't meant to stay `any`*/
+export type $FixMe = any;
+/** For `any`s that we don't care about */
+export type $IntentionalAny = any;
+export type VoidFn = () => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,MAAM,MAAM,GAAG,GAAG,CAAA;AACxB,0CAA0C;AAC1C,MAAM,MAAM,eAAe,GAAG,GAAG,CAAA;AAEjC,MAAM,MAAM,MAAM,GAAG,MAAM,IAAI,CAAA"}

package/dist/utils/Stack.d.ts

@@ -0,0 +1,16 @@
+interface Node<Data> {
+    next: undefined | Node<Data>;
+    data: Data;
+}
+/**
+ * Just a simple LinkedList
+ */
+export default class Stack<Data> {
+    _head: undefined | Node<Data>;
+    constructor();
+    peek(): Data | undefined;
+    pop(): Data | undefined;
+    push(data: Data): void;
+}
+export {};
+//# sourceMappingURL=Stack.d.ts.map

package/dist/utils/Stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stack.d.ts","sourceRoot":"","sources":["../../src/utils/Stack.ts"],"names":[],"mappings":"AAAA,UAAU,IAAI,CAAC,IAAI;IACjB,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IAC5B,IAAI,EAAE,IAAI,CAAA;CACX;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,KAAK,CAAC,IAAI;IAC7B,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;;IAM7B,IAAI;IAIJ,GAAG;IASH,IAAI,CAAC,IAAI,EAAE,IAAI;CAIhB"}

package/dist/utils/typeTestUtils.d.ts

@@ -0,0 +1,11 @@
+import type { $IntentionalAny } from '../types';
+/**
+ * Useful in type tests, such as: const a: SomeType = _any
+ */
+export declare const _any: $IntentionalAny;
+/**
+ * Useful in typeTests. If you want to ensure that value v follows type V,
+ * just write `expectType<V>(v)`
+ */
+export declare const expectType: <T extends unknown>(v: T) => T;
+//# sourceMappingURL=typeTestUtils.d.ts.map

package/dist/utils/typeTestUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeTestUtils.d.ts","sourceRoot":"","sources":["../../src/utils/typeTestUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,UAAU,CAAA;AAE7C;;GAEG;AACH,eAAO,MAAM,IAAI,EAAE,eAAsB,CAAA;AAEzC;;;GAGG;AACH,eAAO,MAAM,UAAU,gCAAoC,CAAA"}

package/dist/utils/updateDeep.d.ts

@@ -0,0 +1,3 @@
+import type { $IntentionalAny } from '../types';
+export default function updateDeep<S>(state: S, path: (string | number | undefined)[], reducer: (...args: $IntentionalAny[]) => $IntentionalAny): S;
+//# sourceMappingURL=updateDeep.d.ts.map

package/dist/utils/updateDeep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateDeep.d.ts","sourceRoot":"","sources":["../../src/utils/updateDeep.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,eAAe,EAAC,MAAM,UAAU,CAAA;AAErD,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,CAAC,EAClC,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,EAAE,EACrC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,eAAe,EAAE,KAAK,eAAe,GACvD,CAAC,CAGH"}

package/dist/val.d.ts

@@ -0,0 +1,14 @@
+import type { Prism } from './prism/Interface';
+import type { PointerType } from './pointer';
+/**
+ * Convenience function that returns a plain value from its argument, whether it
+ * is a pointer, a prism or a plain value itself.
+ *
+ * @remarks
+ * For pointers, the value is returned by first creating a prism, so it is
+ * reactive e.g. when used in a `prism`.
+ *
+ * @param input - The argument to return a value from.
+ */
+export declare const val: <P extends PointerType<any> | Prism<any> | null | undefined>(input: P) => P extends PointerType<infer T> ? T : P extends Prism<infer T_1> ? T_1 : P extends null | undefined ? P : unknown;
+//# sourceMappingURL=val.d.ts.map

package/dist/val.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"val.d.ts","sourceRoot":"","sources":["../src/val.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,mBAAmB,CAAA;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,WAAW,CAAA;AAK1C;;;;;;;;;GASG;AAEH,eAAO,MAAM,GAAG,4LAsBf,CAAA"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@tomorrowevening/theatre-dataverse",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Colin Duffy",
+    "email": "colin@tomorrowevening.com",
+    "url": "https://tomorrowevening.com/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomorrowevening/theatre",
+    "directory": "packages/dataverse"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node ../../devEnv/ensurePublishing.js",
+    "typecheck": "yarn run build:ts",
+    "build": "run-s build:ts build:js build:api-json",
+    "build:ts": "tsc --build ./tsconfig.json",
+    "build:js": "tsx ./devEnv/build.ts",
+    "build:api-json": "api-extractor run --local --config devEnv/api-extractor.json",
+    "prepublish": "node ../../devEnv/ensurePublishing.js",
+    "clean": "rm -rf ./dist && rm -f tsconfig.tsbuildinfo",
+    "docs": "typedoc src/index.ts --out api --plugin typedoc-plugin-markdown --readme none",
+    "precommit": "yarn run docs"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.36.4",
+    "@types/jest": "^26.0.23",
+    "@types/lodash-es": "^4.17.4",
+    "@types/node": "^15.6.2",
+    "esbuild": "^0.12.15",
+    "npm-run-all": "^4.1.5",
+    "tsx": "4.7.0",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-markdown": "^3.15.4",
+    "typescript": "5.1.6"
+  },
+  "dependencies": {
+    "lodash-es": "^4.17.21"
+  }
+}