More docs for dataverse
This commit is contained in:
Aria Minaei
parent
327b859ed4
commit
c8430050a8
15 changed files with 2923 additions and 67 deletions
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