theatre/packages/dataverse/api

@theatre/dataverse

@theatre/dataverse

The animation-optimized FRP library powering the internals of Theatre.js.

Table of contents

Namespaces

• prism

Classes

• Atom
• PointerProxy
• Ticker

Interfaces

• PointerToPrismProvider
• Prism

Type Aliases

• Pointer
• PointerMeta
• PointerType

Functions

• getPointerParts
• isPointer
• isPrism
• iterateAndCountTicks
• iterateOver
• pointer
• pointerToPrism
• prism
• val

Type Aliases

Pointer

Ƭ Pointer<O>: PointerType<O> & PointerInner<Exclude<O, undefined>, undefined extends O ? undefined : never>

The type of Atom pointers. See pointer() 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:

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+ might be able to help us.

Type parameters

Name
O

Defined in

pointer.ts:64

---

PointerMeta

Ƭ PointerMeta: Object

Type declaration

Name	Type
path	(string | number)[]
root	{}

Defined in

pointer.ts:5

---

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

Functions

getPointerParts

▸ getPointerParts<_>(p): Object

Returns the root object and the path of the pointer.

Type parameters

Name
_

Parameters

Name	Type	Description
p	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

const {root, path} = getPointerParts(pointer)

Defined in

pointer.ts:136

---

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

---

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

---

iterateAndCountTicks

▸ iterateAndCountTicks<V>(pointerOrPrism): Generator<{ ticks: number ; value: V }, void, void>

Type parameters

Name
V

Parameters

Name	Type
pointerOrPrism	Prism<V> | Pointer<V>

Returns

Generator<{ ticks: number ; value: V }, void, void>

Defined in

prism/iterateAndCountTicks.ts:7

---

iterateOver

▸ iterateOver<V>(pointerOrPrism): Generator<V, void, void>

Type parameters

Name
V

Parameters

Name	Type
pointerOrPrism	Prism<V> | Pointer<V>

Returns

Generator<V, void, void>

Defined in

prism/iterateOver.ts:8

---

pointer

▸ pointer<O>(args): Pointer<O>

Creates a pointer to a (nested) property of an Atom.

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<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

// 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

---

pointerToPrism

▸ pointerToPrism<P>(pointer): Prism<P extends 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<any>

Parameters

Name	Type	Description
pointer	P	The pointer to return the prism at.

Returns

Prism<P extends PointerType<T> ? T : void>

Defined in

pointerToPrism.ts:41

---

prism

▸ prism<T>(fn): Prism<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<T>

Defined in

prism/prism.ts:817

---

val

▸ val<P>(input): P extends PointerType<T> ? T : P extends Prism<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<any> | PointerType<any>

Parameters

Name	Type	Description
input	P	The argument to return a value from.

Returns

P extends PointerType<T> ? T : P extends Prism<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