More docs for dataverse
This commit is contained in:
Aria Minaei
parent
327b859ed4
commit
c8430050a8
15 changed files with 2923 additions and 67 deletions
1
packages/dataverse/api/.nojekyll
Normal file
1
packages/dataverse/api/.nojekyll
Normal file
|
|
@ -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.
|
||||
402
packages/dataverse/api/README.md
Normal file
402
packages/dataverse/api/README.md
Normal file
|
|
@ -0,0 +1,402 @@
|
|||
@theatre/dataverse
|
||||
|
||||
# @theatre/dataverse
|
||||
|
||||
The animation-optimized FRP library powering the internals of Theatre.js.
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Namespaces
|
||||
|
||||
- [prism](modules/prism.md)
|
||||
|
||||
### Classes
|
||||
|
||||
- [Atom](classes/Atom.md)
|
||||
- [PointerProxy](classes/PointerProxy.md)
|
||||
- [Ticker](classes/Ticker.md)
|
||||
|
||||
### Interfaces
|
||||
|
||||
- [PointerToPrismProvider](interfaces/PointerToPrismProvider.md)
|
||||
- [Prism](interfaces/Prism-1.md)
|
||||
|
||||
### Type Aliases
|
||||
|
||||
- [Pointer](README.md#pointer)
|
||||
- [PointerMeta](README.md#pointermeta)
|
||||
- [PointerType](README.md#pointertype)
|
||||
|
||||
### Functions
|
||||
|
||||
- [getPointerParts](README.md#getpointerparts)
|
||||
- [isPointer](README.md#ispointer)
|
||||
- [isPrism](README.md#isprism)
|
||||
- [iterateAndCountTicks](README.md#iterateandcountticks)
|
||||
- [iterateOver](README.md#iterateover)
|
||||
- [pointer](README.md#pointer-1)
|
||||
- [pointerToPrism](README.md#pointertoprism)
|
||||
- [prism](README.md#prism)
|
||||
- [val](README.md#val)
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### Pointer
|
||||
|
||||
Ƭ **Pointer**<`O`\>: [`PointerType`](README.md#pointertype)<`O`\> & `PointerInner`<`Exclude`<`O`, `undefined`\>, `undefined` extends `O` ? `undefined` : `never`\>
|
||||
|
||||
The type of [Atom](classes/Atom.md) pointers. See [pointer()](README.md#pointer-1) for an
|
||||
explanation of pointers.
|
||||
|
||||
**`See`**
|
||||
|
||||
Atom
|
||||
|
||||
**`Remarks`**
|
||||
|
||||
The Pointer type is quite tricky because it doesn't play well with `any` and other inexact types.
|
||||
Here is an example that one would expect to work, but currently doesn't:
|
||||
```ts
|
||||
declare function expectAnyPointer(pointer: Pointer<any>): void
|
||||
|
||||
expectAnyPointer(null as Pointer<{}>) // this shows as a type error because Pointer<{}> is not assignable to Pointer<any>, even though it should
|
||||
```
|
||||
|
||||
The current solution is to just avoid using `any` with pointer-related code (or type-test it well).
|
||||
But if you enjoy solving typescript puzzles, consider fixing this :)
|
||||
Potentially, [TypeScript variance annotations in 4.7+](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7-beta/#optional-variance-annotations-for-type-parameters)
|
||||
might be able to help us.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `O` |
|
||||
|
||||
#### Defined in
|
||||
|
||||
[pointer.ts:64](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/pointer.ts#L64)
|
||||
|
||||
___
|
||||
|
||||
### PointerMeta
|
||||
|
||||
Ƭ **PointerMeta**: `Object`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `path` | (`string` \| `number`)[] |
|
||||
| `root` | {} |
|
||||
|
||||
#### Defined in
|
||||
|
||||
[pointer.ts:5](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/pointer.ts#L5)
|
||||
|
||||
___
|
||||
|
||||
### PointerType
|
||||
|
||||
Ƭ **PointerType**<`O`\>: `Object`
|
||||
|
||||
A wrapper type for the type a `Pointer` points to.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `O` |
|
||||
|
||||
#### Type declaration
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `$$__pointer_type` | `O` | Only accessible via the type system. This is a helper for getting the underlying pointer type via the type space. |
|
||||
|
||||
#### Defined in
|
||||
|
||||
[pointer.ts:35](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/pointer.ts#L35)
|
||||
|
||||
## Functions
|
||||
|
||||
### getPointerParts
|
||||
|
||||
▸ **getPointerParts**<`_`\>(`p`): `Object`
|
||||
|
||||
Returns the root object and the path of the pointer.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `_` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `p` | [`Pointer`](README.md#pointer)<`_`\> | The pointer. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Object`
|
||||
|
||||
An object with two properties: `root`-the root object or the pointer, and `path`-the path of the pointer. `path` is an array of the property-chain.
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `path` | `PathToProp` |
|
||||
| `root` | {} |
|
||||
|
||||
**`Example`**
|
||||
|
||||
```ts
|
||||
const {root, path} = getPointerParts(pointer)
|
||||
```
|
||||
|
||||
#### Defined in
|
||||
|
||||
[pointer.ts:136](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/pointer.ts#L136)
|
||||
|
||||
___
|
||||
|
||||
### isPointer
|
||||
|
||||
▸ **isPointer**(`p`): p is Pointer<unknown\>
|
||||
|
||||
Returns whether `p` is a pointer.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `p` | `any` |
|
||||
|
||||
#### Returns
|
||||
|
||||
p is Pointer<unknown\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[pointer.ts:187](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/pointer.ts#L187)
|
||||
|
||||
___
|
||||
|
||||
### isPrism
|
||||
|
||||
▸ **isPrism**(`d`): d is Prism<unknown\>
|
||||
|
||||
Returns whether `d` is a prism.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `d` | `any` |
|
||||
|
||||
#### Returns
|
||||
|
||||
d is Prism<unknown\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/Interface.ts:66](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/Interface.ts#L66)
|
||||
|
||||
___
|
||||
|
||||
### iterateAndCountTicks
|
||||
|
||||
▸ **iterateAndCountTicks**<`V`\>(`pointerOrPrism`): `Generator`<{ `ticks`: `number` ; `value`: `V` }, `void`, `void`\>
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `V` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `pointerOrPrism` | [`Prism`](interfaces/Prism-1.md)<`V`\> \| [`Pointer`](README.md#pointer)<`V`\> |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Generator`<{ `ticks`: `number` ; `value`: `V` }, `void`, `void`\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/iterateAndCountTicks.ts:7](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/iterateAndCountTicks.ts#L7)
|
||||
|
||||
___
|
||||
|
||||
### iterateOver
|
||||
|
||||
▸ **iterateOver**<`V`\>(`pointerOrPrism`): `Generator`<`V`, `void`, `void`\>
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `V` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `pointerOrPrism` | [`Prism`](interfaces/Prism-1.md)<`V`\> \| [`Pointer`](README.md#pointer)<`V`\> |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Generator`<`V`, `void`, `void`\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/iterateOver.ts:8](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/iterateOver.ts#L8)
|
||||
|
||||
___
|
||||
|
||||
### pointer
|
||||
|
||||
▸ **pointer**<`O`\>(`args`): [`Pointer`](README.md#pointer)<`O`\>
|
||||
|
||||
Creates a pointer to a (nested) property of an [Atom](classes/Atom.md).
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name | Description |
|
||||
| :------ | :------ |
|
||||
| `O` | The type of the value being pointed to. |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `args` | `Object` | The pointer parameters. |
|
||||
| `args.path?` | (`string` \| `number`)[] | - |
|
||||
| `args.root` | `Object` | - |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`Pointer`](README.md#pointer)<`O`\>
|
||||
|
||||
**`Remarks`**
|
||||
|
||||
Pointers are used to make prisms of properties or nested properties of
|
||||
Atom|Atoms.
|
||||
|
||||
Pointers also allow easy construction of new pointers pointing to nested members
|
||||
of the root object, by simply using property chaining. E.g. `somePointer.a.b` will
|
||||
create a new pointer that has `'a'` and `'b'` added to the path of `somePointer`.
|
||||
|
||||
**`Example`**
|
||||
|
||||
```ts
|
||||
// Here, sum is a prism that updates whenever the a or b prop of someAtom does.
|
||||
const sum = prism(() => {
|
||||
return val(pointer({root: someAtom, path: ['a']})) + val(pointer({root: someAtom, path: ['b']}));
|
||||
});
|
||||
|
||||
// Note, atoms have a convenience Atom.pointer property that points to the root,
|
||||
// which you would normally use in this situation.
|
||||
const sum = prism(() => {
|
||||
return val(someAtom.pointer.a) + val(someAtom.pointer.b);
|
||||
});
|
||||
```
|
||||
|
||||
#### Defined in
|
||||
|
||||
[pointer.ts:172](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/pointer.ts#L172)
|
||||
|
||||
___
|
||||
|
||||
### pointerToPrism
|
||||
|
||||
▸ **pointerToPrism**<`P`\>(`pointer`): [`Prism`](interfaces/Prism-1.md)<`P` extends [`PointerType`](README.md#pointertype)<`T`\> ? `T` : `void`\>
|
||||
|
||||
Returns a prism of the value at the provided pointer. Prisms are
|
||||
cached per pointer.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `P` | extends [`PointerType`](README.md#pointertype)<`any`\> |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `pointer` | `P` | The pointer to return the prism at. |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`Prism`](interfaces/Prism-1.md)<`P` extends [`PointerType`](README.md#pointertype)<`T`\> ? `T` : `void`\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[pointerToPrism.ts:41](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/pointerToPrism.ts#L41)
|
||||
|
||||
___
|
||||
|
||||
### prism
|
||||
|
||||
▸ **prism**<`T`\>(`fn`): [`Prism`](interfaces/Prism-1.md)<`T`\>
|
||||
|
||||
Creates a prism from the passed function that adds all prisms referenced
|
||||
in it as dependencies, and reruns the function when these change.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `T` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `fn` | () => `T` | The function to rerun when the prisms referenced in it change. |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`Prism`](interfaces/Prism-1.md)<`T`\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:817](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L817)
|
||||
|
||||
___
|
||||
|
||||
### val
|
||||
|
||||
▸ **val**<`P`\>(`input`): `P` extends [`PointerType`](README.md#pointertype)<`T`\> ? `T` : `P` extends [`Prism`](interfaces/Prism-1.md)<`T`\> ? `T` : `P` extends `undefined` \| ``null`` ? `P` : `unknown`
|
||||
|
||||
Convenience function that returns a plain value from its argument, whether it
|
||||
is a pointer, a prism or a plain value itself.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `P` | extends `undefined` \| ``null`` \| [`Prism`](interfaces/Prism-1.md)<`any`\> \| [`PointerType`](README.md#pointertype)<`any`\> |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `input` | `P` | The argument to return a value from. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`P` extends [`PointerType`](README.md#pointertype)<`T`\> ? `T` : `P` extends [`Prism`](interfaces/Prism-1.md)<`T`\> ? `T` : `P` extends `undefined` \| ``null`` ? `P` : `unknown`
|
||||
|
||||
**`Remarks`**
|
||||
|
||||
For pointers, the value is returned by first creating a prism, so it is
|
||||
reactive e.g. when used in a `prism`.
|
||||
|
||||
#### Defined in
|
||||
|
||||
[val.ts:19](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/val.ts#L19)
|
||||
381
packages/dataverse/api/classes/Atom.md
Normal file
381
packages/dataverse/api/classes/Atom.md
Normal file
|
|
@ -0,0 +1,381 @@
|
|||
[@theatre/dataverse](../README.md) / Atom
|
||||
|
||||
# Class: Atom<State\>
|
||||
|
||||
Wraps an object whose (sub)properties can be individually tracked.
|
||||
|
||||
## Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `State` |
|
||||
|
||||
## Implements
|
||||
|
||||
- [`PointerToPrismProvider`](../interfaces/PointerToPrismProvider.md)
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Constructors
|
||||
|
||||
- [constructor](Atom.md#constructor)
|
||||
|
||||
### Properties
|
||||
|
||||
- [\_currentState](Atom.md#_currentstate)
|
||||
- [\_rootScope](Atom.md#_rootscope)
|
||||
- [pointer](Atom.md#pointer)
|
||||
- [prism](Atom.md#prism)
|
||||
|
||||
### Methods
|
||||
|
||||
- [\_checkUpdates](Atom.md#_checkupdates)
|
||||
- [\_getIn](Atom.md#_getin)
|
||||
- [\_getOrCreateScopeForPath](Atom.md#_getorcreatescopeforpath)
|
||||
- [\_onPointerValueChange](Atom.md#_onpointervaluechange)
|
||||
- [get](Atom.md#get)
|
||||
- [getByPointer](Atom.md#getbypointer)
|
||||
- [pointerToPrism](Atom.md#pointertoprism)
|
||||
- [reduce](Atom.md#reduce)
|
||||
- [reduceByPointer](Atom.md#reducebypointer)
|
||||
- [set](Atom.md#set)
|
||||
- [setByPointer](Atom.md#setbypointer)
|
||||
|
||||
## Constructors
|
||||
|
||||
### constructor
|
||||
|
||||
• **new Atom**<`State`\>(`initialState`)
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `State` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `initialState` | `State` |
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:119](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L119)
|
||||
|
||||
## Properties
|
||||
|
||||
### \_currentState
|
||||
|
||||
• `Private` **\_currentState**: `State`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:101](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L101)
|
||||
|
||||
___
|
||||
|
||||
### \_rootScope
|
||||
|
||||
• `Private` `Readonly` **\_rootScope**: `Scope`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:106](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L106)
|
||||
|
||||
___
|
||||
|
||||
### pointer
|
||||
|
||||
• `Readonly` **pointer**: [`Pointer`](../README.md#pointer)<`State`\>
|
||||
|
||||
Convenience property that gives you a pointer to the root of the atom.
|
||||
|
||||
**`Remarks`**
|
||||
|
||||
Equivalent to `pointer({ root: thisAtom, path: [] })`.
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:113](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L113)
|
||||
|
||||
___
|
||||
|
||||
### prism
|
||||
|
||||
• `Readonly` **prism**: [`Prism`](../interfaces/Prism-1.md)<`State`\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:115](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L115)
|
||||
|
||||
## Methods
|
||||
|
||||
### \_checkUpdates
|
||||
|
||||
▸ `Private` **_checkUpdates**(`scope`, `oldState`, `newState`): `void`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `scope` | `Scope` |
|
||||
| `oldState` | `unknown` |
|
||||
| `newState` | `unknown` |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:218](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L218)
|
||||
|
||||
___
|
||||
|
||||
### \_getIn
|
||||
|
||||
▸ `Private` **_getIn**(`path`): `unknown`
|
||||
|
||||
Gets the state of the atom at `path`.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `path` | (`string` \| `number`)[] |
|
||||
|
||||
#### Returns
|
||||
|
||||
`unknown`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:166](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L166)
|
||||
|
||||
___
|
||||
|
||||
### \_getOrCreateScopeForPath
|
||||
|
||||
▸ `Private` **_getOrCreateScopeForPath**(`path`): `Scope`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `path` | (`string` \| `number`)[] |
|
||||
|
||||
#### Returns
|
||||
|
||||
`Scope`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:240](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L240)
|
||||
|
||||
___
|
||||
|
||||
### \_onPointerValueChange
|
||||
|
||||
▸ `Private` **_onPointerValueChange**<`P`\>(`pointer`, `cb`): () => `void`
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `P` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `pointer` | [`Pointer`](../README.md#pointer)<`P`\> |
|
||||
| `cb` | (`v`: `P`) => `void` |
|
||||
|
||||
#### Returns
|
||||
|
||||
`fn`
|
||||
|
||||
▸ (): `void`
|
||||
|
||||
##### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:248](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L248)
|
||||
|
||||
___
|
||||
|
||||
### get
|
||||
|
||||
▸ **get**(): `State`
|
||||
|
||||
#### Returns
|
||||
|
||||
`State`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:136](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L136)
|
||||
|
||||
___
|
||||
|
||||
### getByPointer
|
||||
|
||||
▸ **getByPointer**<`S`\>(`pointerOrFn`): `S`
|
||||
|
||||
Returns the value at the given pointer
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `S` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `pointerOrFn` | [`Pointer`](../README.md#pointer)<`S`\> \| (`p`: [`Pointer`](../README.md#pointer)<`State`\>) => [`Pointer`](../README.md#pointer)<`S`\> | A pointer to the desired path. Could also be a function returning a pointer Example ```ts const atom = atom({ a: { b: 1 } }) atom.getByPointer(atom.pointer.a.b) // 1 atom.getByPointer((p) => p.a.b) // 1 ``` |
|
||||
|
||||
#### Returns
|
||||
|
||||
`S`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:152](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L152)
|
||||
|
||||
___
|
||||
|
||||
### pointerToPrism
|
||||
|
||||
▸ **pointerToPrism**<`P`\>(`pointer`): [`Prism`](../interfaces/Prism-1.md)<`P`\>
|
||||
|
||||
Returns a new prism of the value at the provided path.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `P` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `pointer` | [`Pointer`](../README.md#pointer)<`P`\> | The path to create the prism at. ```ts const pr = atom({ a: { b: 1 } }).pointerToPrism(atom.pointer.a.b) pr.getValue() // 1 ``` |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`Prism`](../interfaces/Prism-1.md)<`P`\>
|
||||
|
||||
#### Implementation of
|
||||
|
||||
[PointerToPrismProvider](../interfaces/PointerToPrismProvider.md).[pointerToPrism](../interfaces/PointerToPrismProvider.md#pointertoprism)
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:271](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L271)
|
||||
|
||||
___
|
||||
|
||||
### reduce
|
||||
|
||||
▸ **reduce**(`fn`): `void`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `fn` | (`state`: `State`) => `State` |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:170](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L170)
|
||||
|
||||
___
|
||||
|
||||
### reduceByPointer
|
||||
|
||||
▸ **reduceByPointer**<`S`\>(`pointerOrFn`, `reducer`): `void`
|
||||
|
||||
Reduces the value at the given pointer
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `S` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `pointerOrFn` | [`Pointer`](../README.md#pointer)<`S`\> \| (`p`: [`Pointer`](../README.md#pointer)<`State`\>) => [`Pointer`](../README.md#pointer)<`S`\> | A pointer to the desired path. Could also be a function returning a pointer Example ```ts const atom = atom({ a: { b: 1 } }) atom.reduceByPointer(atom.pointer.a.b, (b) => b + 1) // atom.get().a.b === 2 atom.reduceByPointer((p) => p.a.b, (b) => b + 1) // atom.get().a.b === 2 ``` |
|
||||
| `reducer` | (`s`: `S`) => `S` | - |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:186](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L186)
|
||||
|
||||
___
|
||||
|
||||
### set
|
||||
|
||||
▸ **set**(`newState`): `void`
|
||||
|
||||
Sets the state of the atom.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `newState` | `State` | The new state of the atom. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:129](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L129)
|
||||
|
||||
___
|
||||
|
||||
### setByPointer
|
||||
|
||||
▸ **setByPointer**<`S`\>(`pointerOrFn`, `val`): `void`
|
||||
|
||||
Sets the value at the given pointer
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `S` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `pointerOrFn` | [`Pointer`](../README.md#pointer)<`S`\> \| (`p`: [`Pointer`](../README.md#pointer)<`State`\>) => [`Pointer`](../README.md#pointer)<`S`\> | A pointer to the desired path. Could also be a function returning a pointer Example ```ts const atom = atom({ a: { b: 1 } }) atom.setByPointer(atom.pointer.a.b, 2) // atom.get().a.b === 2 atom.setByPointer((p) => p.a.b, 2) // atom.get().a.b === 2 ``` |
|
||||
| `val` | `S` | - |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Atom.ts:211](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Atom.ts#L211)
|
||||
138
packages/dataverse/api/classes/PointerProxy.md
Normal file
138
packages/dataverse/api/classes/PointerProxy.md
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
[@theatre/dataverse](../README.md) / PointerProxy
|
||||
|
||||
# Class: PointerProxy<O\>
|
||||
|
||||
Allows creating pointer-prisms where the pointer can be switched out.
|
||||
|
||||
**`Remarks`**
|
||||
|
||||
This allows reacting not just to value changes at a certain pointer, but changes
|
||||
to the proxied pointer too.
|
||||
|
||||
## Type parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `O` | extends `Object` |
|
||||
|
||||
## Implements
|
||||
|
||||
- [`PointerToPrismProvider`](../interfaces/PointerToPrismProvider.md)
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Constructors
|
||||
|
||||
- [constructor](PointerProxy.md#constructor)
|
||||
|
||||
### Properties
|
||||
|
||||
- [\_currentPointerBox](PointerProxy.md#_currentpointerbox)
|
||||
- [pointer](PointerProxy.md#pointer)
|
||||
|
||||
### Methods
|
||||
|
||||
- [pointerToPrism](PointerProxy.md#pointertoprism)
|
||||
- [setPointer](PointerProxy.md#setpointer)
|
||||
|
||||
## Constructors
|
||||
|
||||
### constructor
|
||||
|
||||
• **new PointerProxy**<`O`\>(`currentPointer`)
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `O` | extends `Object` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `currentPointer` | [`Pointer`](../README.md#pointer)<`O`\> |
|
||||
|
||||
#### Defined in
|
||||
|
||||
[PointerProxy.ts:34](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/PointerProxy.ts#L34)
|
||||
|
||||
## Properties
|
||||
|
||||
### \_currentPointerBox
|
||||
|
||||
• `Private` `Readonly` **\_currentPointerBox**: [`Atom`](Atom.md)<[`Pointer`](../README.md#pointer)<`O`\>\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[PointerProxy.ts:25](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/PointerProxy.ts#L25)
|
||||
|
||||
___
|
||||
|
||||
### pointer
|
||||
|
||||
• `Readonly` **pointer**: [`Pointer`](../README.md#pointer)<`O`\>
|
||||
|
||||
Convenience pointer pointing to the root of this PointerProxy.
|
||||
|
||||
**`Remarks`**
|
||||
|
||||
Allows convenient use of [pointerToPrism](PointerProxy.md#pointertoprism) and [val](../README.md#val).
|
||||
|
||||
#### Defined in
|
||||
|
||||
[PointerProxy.ts:32](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/PointerProxy.ts#L32)
|
||||
|
||||
## Methods
|
||||
|
||||
### pointerToPrism
|
||||
|
||||
▸ **pointerToPrism**<`P`\>(`pointer`): [`Prism`](../interfaces/Prism-1.md)<`P`\>
|
||||
|
||||
Returns a prism of the value at the provided sub-path of the proxied pointer.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `P` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `pointer` | [`Pointer`](../README.md#pointer)<`P`\> |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`Prism`](../interfaces/Prism-1.md)<`P`\>
|
||||
|
||||
#### Implementation of
|
||||
|
||||
[PointerToPrismProvider](../interfaces/PointerToPrismProvider.md).[pointerToPrism](../interfaces/PointerToPrismProvider.md#pointertoprism)
|
||||
|
||||
#### Defined in
|
||||
|
||||
[PointerProxy.ts:52](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/PointerProxy.ts#L52)
|
||||
|
||||
___
|
||||
|
||||
### setPointer
|
||||
|
||||
▸ **setPointer**(`p`): `void`
|
||||
|
||||
Sets the underlying pointer.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `p` | [`Pointer`](../README.md#pointer)<`O`\> | The pointer to be proxied. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[PointerProxy.ts:43](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/PointerProxy.ts#L43)
|
||||
372
packages/dataverse/api/classes/Ticker.md
Normal file
372
packages/dataverse/api/classes/Ticker.md
Normal file
|
|
@ -0,0 +1,372 @@
|
|||
[@theatre/dataverse](../README.md) / Ticker
|
||||
|
||||
# Class: Ticker
|
||||
|
||||
The Ticker class helps schedule callbacks. Scheduled callbacks are executed per tick. Ticks can be triggered by an
|
||||
external scheduling strategy, e.g. a raf.
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Constructors
|
||||
|
||||
- [constructor](Ticker.md#constructor)
|
||||
|
||||
### Properties
|
||||
|
||||
- [\_\_ticks](Ticker.md#__ticks)
|
||||
- [\_conf](Ticker.md#_conf)
|
||||
- [\_dormant](Ticker.md#_dormant)
|
||||
- [\_numberOfDormantTicks](Ticker.md#_numberofdormantticks)
|
||||
- [\_scheduledForNextTick](Ticker.md#_scheduledfornexttick)
|
||||
- [\_scheduledForThisOrNextTick](Ticker.md#_scheduledforthisornexttick)
|
||||
- [\_ticking](Ticker.md#_ticking)
|
||||
- [\_timeAtCurrentTick](Ticker.md#_timeatcurrenttick)
|
||||
|
||||
### Accessors
|
||||
|
||||
- [dormant](Ticker.md#dormant)
|
||||
- [time](Ticker.md#time)
|
||||
|
||||
### Methods
|
||||
|
||||
- [\_goActive](Ticker.md#_goactive)
|
||||
- [\_goDormant](Ticker.md#_godormant)
|
||||
- [\_tick](Ticker.md#_tick)
|
||||
- [offNextTick](Ticker.md#offnexttick)
|
||||
- [offThisOrNextTick](Ticker.md#offthisornexttick)
|
||||
- [onNextTick](Ticker.md#onnexttick)
|
||||
- [onThisOrNextTick](Ticker.md#onthisornexttick)
|
||||
- [tick](Ticker.md#tick)
|
||||
|
||||
## Constructors
|
||||
|
||||
### constructor
|
||||
|
||||
• **new Ticker**(`_conf?`)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `_conf?` | `Object` |
|
||||
| `_conf.onActive?` | () => `void` |
|
||||
| `_conf.onDormant?` | () => `void` |
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:43](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L43)
|
||||
|
||||
## Properties
|
||||
|
||||
### \_\_ticks
|
||||
|
||||
• **\_\_ticks**: `number` = `0`
|
||||
|
||||
Counts up for every tick executed.
|
||||
Internally, this is used to measure ticks per second.
|
||||
|
||||
This is "public" to TypeScript, because it's a tool for performance measurements.
|
||||
Consider this as experimental, and do not rely on it always being here in future releases.
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:41](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L41)
|
||||
|
||||
___
|
||||
|
||||
### \_conf
|
||||
|
||||
• `Private` `Optional` **\_conf**: `Object`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `onActive?` | () => `void` |
|
||||
| `onDormant?` | () => `void` |
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:44](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L44)
|
||||
|
||||
___
|
||||
|
||||
### \_dormant
|
||||
|
||||
• `Private` **\_dormant**: `boolean` = `true`
|
||||
|
||||
Whether the Ticker is dormant
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:24](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L24)
|
||||
|
||||
___
|
||||
|
||||
### \_numberOfDormantTicks
|
||||
|
||||
• `Private` **\_numberOfDormantTicks**: `number` = `0`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:26](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L26)
|
||||
|
||||
___
|
||||
|
||||
### \_scheduledForNextTick
|
||||
|
||||
• `Private` **\_scheduledForNextTick**: `Set`<`ICallback`\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:17](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L17)
|
||||
|
||||
___
|
||||
|
||||
### \_scheduledForThisOrNextTick
|
||||
|
||||
• `Private` **\_scheduledForThisOrNextTick**: `Set`<`ICallback`\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:16](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L16)
|
||||
|
||||
___
|
||||
|
||||
### \_ticking
|
||||
|
||||
• `Private` **\_ticking**: `boolean` = `false`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:19](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L19)
|
||||
|
||||
___
|
||||
|
||||
### \_timeAtCurrentTick
|
||||
|
||||
• `Private` **\_timeAtCurrentTick**: `number`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:18](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L18)
|
||||
|
||||
## Accessors
|
||||
|
||||
### dormant
|
||||
|
||||
• `get` **dormant**(): `boolean`
|
||||
|
||||
Whether the Ticker is dormant
|
||||
|
||||
#### Returns
|
||||
|
||||
`boolean`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:31](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L31)
|
||||
|
||||
___
|
||||
|
||||
### time
|
||||
|
||||
• `get` **time**(): `number`
|
||||
|
||||
The time at the start of the current tick if there is a tick in progress, otherwise defaults to
|
||||
`performance.now()`.
|
||||
|
||||
#### Returns
|
||||
|
||||
`number`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:122](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L122)
|
||||
|
||||
## Methods
|
||||
|
||||
### \_goActive
|
||||
|
||||
▸ `Private` **_goActive**(): `void`
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:128](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L128)
|
||||
|
||||
___
|
||||
|
||||
### \_goDormant
|
||||
|
||||
▸ `Private` **_goDormant**(): `void`
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:134](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L134)
|
||||
|
||||
___
|
||||
|
||||
### \_tick
|
||||
|
||||
▸ `Private` **_tick**(`iterationNumber`): `void`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `iterationNumber` | `number` |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:184](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L184)
|
||||
|
||||
___
|
||||
|
||||
### offNextTick
|
||||
|
||||
▸ **offNextTick**(`fn`): `void`
|
||||
|
||||
De-registers a fn to be called on the next tick.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `fn` | `ICallback` | The function to be de-registered. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
**`See`**
|
||||
|
||||
onNextTick
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:114](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L114)
|
||||
|
||||
___
|
||||
|
||||
### offThisOrNextTick
|
||||
|
||||
▸ **offThisOrNextTick**(`fn`): `void`
|
||||
|
||||
De-registers a fn to be called either on this tick or the next tick.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `fn` | `ICallback` | The function to be de-registered. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
**`See`**
|
||||
|
||||
onThisOrNextTick
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:103](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L103)
|
||||
|
||||
___
|
||||
|
||||
### onNextTick
|
||||
|
||||
▸ **onNextTick**(`fn`): `void`
|
||||
|
||||
Registers a side effect to be called on the next tick.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `fn` | `ICallback` | The function to be registered. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
**`See`**
|
||||
|
||||
- onThisOrNextTick
|
||||
- offNextTick
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:89](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L89)
|
||||
|
||||
___
|
||||
|
||||
### onThisOrNextTick
|
||||
|
||||
▸ **onThisOrNextTick**(`fn`): `void`
|
||||
|
||||
Registers for fn to be called either on this tick or the next tick.
|
||||
|
||||
If `onThisOrNextTick()` is called while `Ticker.tick()` is running, the
|
||||
side effect _will_ be called within the running tick. If you don't want this
|
||||
behavior, you can use `onNextTick()`.
|
||||
|
||||
Note that `fn` will be added to a `Set()`. Which means, if you call `onThisOrNextTick(fn)`
|
||||
with the same fn twice in a single tick, it'll only run once.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `fn` | `ICallback` | The function to be registered. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
**`See`**
|
||||
|
||||
offThisOrNextTick
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:74](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L74)
|
||||
|
||||
___
|
||||
|
||||
### tick
|
||||
|
||||
▸ **tick**(`t?`): `void`
|
||||
|
||||
Triggers a tick which starts executing the callbacks scheduled for this tick.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `t` | `number` | The time at the tick. |
|
||||
|
||||
#### Returns
|
||||
|
||||
`void`
|
||||
|
||||
**`See`**
|
||||
|
||||
- onThisOrNextTick
|
||||
- onNextTick
|
||||
|
||||
#### Defined in
|
||||
|
||||
[Ticker.ts:149](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/Ticker.ts#L149)
|
||||
44
packages/dataverse/api/interfaces/PointerToPrismProvider.md
Normal file
44
packages/dataverse/api/interfaces/PointerToPrismProvider.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
[@theatre/dataverse](../README.md) / PointerToPrismProvider
|
||||
|
||||
# Interface: PointerToPrismProvider
|
||||
|
||||
Interface for objects that can provide a prism at a certain path.
|
||||
|
||||
## Implemented by
|
||||
|
||||
- [`Atom`](../classes/Atom.md)
|
||||
- [`PointerProxy`](../classes/PointerProxy.md)
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Methods
|
||||
|
||||
- [pointerToPrism](PointerToPrismProvider.md#pointertoprism)
|
||||
|
||||
## Methods
|
||||
|
||||
### pointerToPrism
|
||||
|
||||
▸ **pointerToPrism**<`P`\>(`pointer`): [`Prism`](Prism-1.md)<`P`\>
|
||||
|
||||
Returns a prism of the value at the provided pointer.
|
||||
|
||||
#### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `P` |
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `pointer` | [`Pointer`](../README.md#pointer)<`P`\> |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`Prism`](Prism-1.md)<`P`\>
|
||||
|
||||
#### Defined in
|
||||
|
||||
[pointerToPrism.ts:21](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/pointerToPrism.ts#L21)
|
||||
125
packages/dataverse/api/interfaces/Prism-1.md
Normal file
125
packages/dataverse/api/interfaces/Prism-1.md
Normal file
|
|
@ -0,0 +1,125 @@
|
|||
[@theatre/dataverse](../README.md) / Prism
|
||||
|
||||
# Interface: Prism<V\>
|
||||
|
||||
Common interface for prisms.
|
||||
|
||||
## Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `V` |
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Properties
|
||||
|
||||
- [isHot](Prism-1.md#ishot)
|
||||
- [isPrism](Prism-1.md#isprism)
|
||||
|
||||
### Methods
|
||||
|
||||
- [getValue](Prism-1.md#getvalue)
|
||||
- [keepHot](Prism-1.md#keephot)
|
||||
- [onChange](Prism-1.md#onchange)
|
||||
- [onStale](Prism-1.md#onstale)
|
||||
|
||||
## Properties
|
||||
|
||||
### isHot
|
||||
|
||||
• **isHot**: `boolean`
|
||||
|
||||
Whether the prism is hot.
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/Interface.ts:18](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/Interface.ts#L18)
|
||||
|
||||
___
|
||||
|
||||
### isPrism
|
||||
|
||||
• **isPrism**: ``true``
|
||||
|
||||
Whether the object is a prism.
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/Interface.ts:13](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/Interface.ts#L13)
|
||||
|
||||
## Methods
|
||||
|
||||
### getValue
|
||||
|
||||
▸ **getValue**(): `V`
|
||||
|
||||
Gets the current value of the prism. If the value is stale, it causes the prism to freshen.
|
||||
|
||||
#### Returns
|
||||
|
||||
`V`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/Interface.ts:60](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/Interface.ts#L60)
|
||||
|
||||
___
|
||||
|
||||
### keepHot
|
||||
|
||||
▸ **keepHot**(): `VoidFn`
|
||||
|
||||
Keep the prism hot, even if there are no tappers (subscribers).
|
||||
|
||||
#### Returns
|
||||
|
||||
`VoidFn`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/Interface.ts:34](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/Interface.ts#L34)
|
||||
|
||||
___
|
||||
|
||||
### onChange
|
||||
|
||||
▸ **onChange**(`ticker`, `listener`, `immediate?`): `VoidFn`
|
||||
|
||||
Calls `listener` with a fresh value every time the prism _has_ a new value, throttled by Ticker.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `ticker` | [`Ticker`](../classes/Ticker.md) |
|
||||
| `listener` | (`v`: `V`) => `void` |
|
||||
| `immediate?` | `boolean` |
|
||||
|
||||
#### Returns
|
||||
|
||||
`VoidFn`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/Interface.ts:23](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/Interface.ts#L23)
|
||||
|
||||
___
|
||||
|
||||
### onStale
|
||||
|
||||
▸ **onStale**(`cb`): `VoidFn`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `cb` | () => `void` |
|
||||
|
||||
#### Returns
|
||||
|
||||
`VoidFn`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/Interface.ts:29](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/Interface.ts#L29)
|
||||
395
packages/dataverse/api/modules/prism.md
Normal file
395
packages/dataverse/api/modules/prism.md
Normal file
|
|
@ -0,0 +1,395 @@
|
|||
[@theatre/dataverse](../README.md) / prism
|
||||
|
||||
# Namespace: prism
|
||||
|
||||
Creates a prism from the passed function that adds all prisms referenced
|
||||
in it as dependencies, and reruns the function when these change.
|
||||
|
||||
**`Param`**
|
||||
|
||||
The function to rerun when the prisms referenced in it change.
|
||||
|
||||
## Table of contents
|
||||
|
||||
### Variables
|
||||
|
||||
- [effect](prism.md#effect)
|
||||
- [ensurePrism](prism.md#ensureprism)
|
||||
- [inPrism](prism.md#inprism)
|
||||
- [memo](prism.md#memo)
|
||||
- [ref](prism.md#ref)
|
||||
- [scope](prism.md#scope)
|
||||
- [source](prism.md#source)
|
||||
- [state](prism.md#state)
|
||||
- [sub](prism.md#sub)
|
||||
|
||||
## Variables
|
||||
|
||||
### effect
|
||||
|
||||
• **effect**: (`key`: `string`, `cb`: () => () => `void`, `deps?`: `unknown`[]) => `void`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ (`key`, `cb`, `deps?`): `void`
|
||||
|
||||
An effect hook, similar to React's `useEffect()`, but is not sensitive to call order by using `key`.
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `key` | `string` | the key for the effect. Should be uniqe inside of the prism. |
|
||||
| `cb` | () => () => `void` | the callback function. Requires returning a cleanup function. |
|
||||
| `deps?` | `unknown`[] | the dependency array |
|
||||
|
||||
##### Returns
|
||||
|
||||
`void`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:885](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L885)
|
||||
|
||||
___
|
||||
|
||||
### ensurePrism
|
||||
|
||||
• **ensurePrism**: () => `void`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ (): `void`
|
||||
|
||||
This is useful to make sure your code is running inside a `prism()` call.
|
||||
|
||||
##### Returns
|
||||
|
||||
`void`
|
||||
|
||||
**`Example`**
|
||||
|
||||
```ts
|
||||
import {prism} from '@theatre/dataverse'
|
||||
|
||||
function onlyUsefulInAPrism() {
|
||||
prism.ensurePrism()
|
||||
}
|
||||
|
||||
prism(() => {
|
||||
onlyUsefulInAPrism() // will run fine
|
||||
})
|
||||
|
||||
setTimeout(() => {
|
||||
onlyUsefulInAPrism() // throws an error
|
||||
console.log('This will never get logged')
|
||||
}, 0)
|
||||
```
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:887](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L887)
|
||||
|
||||
___
|
||||
|
||||
### inPrism
|
||||
|
||||
• **inPrism**: () => `boolean`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ (): `boolean`
|
||||
|
||||
##### Returns
|
||||
|
||||
`boolean`
|
||||
|
||||
true if the current function is running inside a `prism()` call.
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:891](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L891)
|
||||
|
||||
___
|
||||
|
||||
### memo
|
||||
|
||||
• **memo**: <T\>(`key`: `string`, `fn`: () => `T`, `deps`: `undefined` \| `any`[] \| readonly `any`[]) => `T`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ <`T`\>(`key`, `fn`, `deps`): `T`
|
||||
|
||||
`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.
|
||||
|
||||
##### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `T` |
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `key` | `string` | The key for the memo. Should be unique inside of the prism |
|
||||
| `fn` | () => `T` | The function to memoize |
|
||||
| `deps` | `undefined` \| `any`[] \| readonly `any`[] | The dependency array. Provide `[]` if you want to the value to be memoized only once and never re-calculated. |
|
||||
|
||||
##### Returns
|
||||
|
||||
`T`
|
||||
|
||||
The result of the function call
|
||||
|
||||
**`Example`**
|
||||
|
||||
```ts
|
||||
const pr = prism(() => {
|
||||
const memoizedReturnValueOfExpensiveFn = prism.memo("memo1", expensiveFn, [])
|
||||
})
|
||||
```
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:886](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L886)
|
||||
|
||||
___
|
||||
|
||||
### ref
|
||||
|
||||
• **ref**: <T\>(`key`: `string`, `initialValue`: `T`) => `IRef`<`T`\>
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ <`T`\>(`key`, `initialValue`): `IRef`<`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.
|
||||
|
||||
##### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `T` |
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `key` | `string` | The key for the ref. Should be unique inside of the prism. |
|
||||
| `initialValue` | `T` | The initial value for the ref. |
|
||||
|
||||
##### Returns
|
||||
|
||||
`IRef`<`T`\>
|
||||
|
||||
`{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
|
||||
})
|
||||
```
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:884](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L884)
|
||||
|
||||
___
|
||||
|
||||
### scope
|
||||
|
||||
• **scope**: <T\>(`key`: `string`, `fn`: () => `T`) => `T`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ <`T`\>(`key`, `fn`): `T`
|
||||
|
||||
##### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `T` |
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------ |
|
||||
| `key` | `string` |
|
||||
| `fn` | () => `T` |
|
||||
|
||||
##### Returns
|
||||
|
||||
`T`
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:889](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L889)
|
||||
|
||||
___
|
||||
|
||||
### source
|
||||
|
||||
• **source**: <V\>(`subscribe`: (`fn`: (`val`: `V`) => `void`) => `VoidFn`, `getValue`: () => `V`) => `V`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ <`V`\>(`subscribe`, `getValue`): `V`
|
||||
|
||||
`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.
|
||||
|
||||
##### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `V` |
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `subscribe` | (`fn`: (`val`: `V`) => `void`) => `VoidFn` | 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. |
|
||||
| `getValue` | () => `V` | A function that returns the current value of the external source. |
|
||||
|
||||
##### Returns
|
||||
|
||||
`V`
|
||||
|
||||
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))
|
||||
}
|
||||
```
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:892](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L892)
|
||||
|
||||
___
|
||||
|
||||
### state
|
||||
|
||||
• **state**: <T\>(`key`: `string`, `initialValue`: `T`) => [`T`, (`val`: `T`) => `void`]
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ <`T`\>(`key`, `initialValue`): [`T`, (`val`: `T`) => `void`]
|
||||
|
||||
A state hook, similar to react's `useState()`.
|
||||
|
||||
##### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `T` |
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `key` | `string` | the key for the state |
|
||||
| `initialValue` | `T` | the initial value |
|
||||
|
||||
##### Returns
|
||||
|
||||
[`T`, (`val`: `T`) => `void`]
|
||||
|
||||
[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
|
||||
})
|
||||
```
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:888](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L888)
|
||||
|
||||
___
|
||||
|
||||
### sub
|
||||
|
||||
• **sub**: <T\>(`key`: `string`, `fn`: () => `T`, `deps`: `undefined` \| `any`[]) => `T`
|
||||
|
||||
#### Type declaration
|
||||
|
||||
▸ <`T`\>(`key`, `fn`, `deps`): `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.
|
||||
|
||||
##### Type parameters
|
||||
|
||||
| Name |
|
||||
| :------ |
|
||||
| `T` |
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------ | :------ |
|
||||
| `key` | `string` | The key for the memo. Should be unique inside of the prism |
|
||||
| `fn` | () => `T` | The function to run inside the prism |
|
||||
| `deps` | `undefined` \| `any`[] | The dependency array. Provide `[]` if you want to the value to be memoized only once and never re-calculated. |
|
||||
|
||||
##### Returns
|
||||
|
||||
`T`
|
||||
|
||||
The value of the inner prism
|
||||
|
||||
#### Defined in
|
||||
|
||||
[prism/prism.ts:890](https://github.com/theatre-js/theatre/blob/327b859ed/packages/dataverse/src/prism/prism.ts#L890)
|
||||
Loading…
Add table
Add a link
Reference in a new issue