@starbeam/tags
Advanced tools
Comparing version 0.0.1-unstable.aeb2ad9 to 0.0.1-unstable.bca55c9
{ | ||
"name": "@starbeam/tags", | ||
"version": "0.0.1-unstable.aeb2ad9", | ||
"type": "module", | ||
"main": "index.ts", | ||
"types": "index.ts", | ||
"version": "0.0.1-unstable.bca55c9", | ||
"main": "dist/index.cjs", | ||
"types": "dist/index.d.ts", | ||
"exports": { | ||
"default": "./index.ts" | ||
"types": "./dist/index.d.ts", | ||
"import": "./dist/index.js", | ||
"default": "./dist/index.cjs" | ||
}, | ||
"publishConfig": { | ||
"exports": { | ||
".": { | ||
"types": "./dist/index.d.ts", | ||
"import": "./dist/index.js", | ||
"default": "./dist/index.cjs" | ||
} | ||
}, | ||
"main": "dist/index.cjs", | ||
"types": "dist/index.d.ts" | ||
"starbeam": { | ||
"type": "library:public" | ||
}, | ||
"starbeam:type": "library:public", | ||
"dependencies": { | ||
"@starbeam/core-utils": "0.8.10-unstable.bca55c9", | ||
"@starbeam/interfaces": "0.8.10-unstable.bca55c9", | ||
"@starbeam/shared": "1.3.8-unstable.bca55c9", | ||
"inspect-utils": "^1.0.1" | ||
}, | ||
"devDependencies": { | ||
"@starbeam-dev/eslint-plugin": "^1.0.4", | ||
"rollup": "^4.0.2", | ||
"@starbeam-dev/compile": "1.2.0" | ||
}, | ||
"files": [ | ||
"dist", | ||
"README.md", | ||
"CHANGELOG.md", | ||
"LICENSE.md" | ||
], | ||
"scripts": { | ||
"build": "rollup -c", | ||
"test:lint": "eslint . --max-warnings 0", | ||
"test:types": "tsc -b" | ||
}, | ||
"dependencies": { | ||
"@starbeam/core-utils": "0.8.10-unstable.aeb2ad9", | ||
"@starbeam/interfaces": "0.8.10-unstable.aeb2ad9", | ||
"@starbeam/shared": "1.3.8-unstable.aeb2ad9" | ||
}, | ||
"devDependencies": { | ||
"@starbeam/eslint-plugin": "workspace:^", | ||
"@starbeam-dev/build-support": "workspace:^", | ||
"rollup": "^3.29.2" | ||
} | ||
} | ||
} |
@@ -41,10 +41,6 @@ This package contains the implementation of "tags". | ||
- A `description` property. This is a rich object that enables the logging and | ||
debugging features of Starbeam. | ||
- A `lastUpdated` property. In composite tags, this is the latest revision of | ||
the tag's children. | ||
- An `id` property. This is a unique identifier for the tag that does not change | ||
over its lifetime. It can be a string, a number or an array of IDs (recursive). | ||
- A `dependencies()` method. This returns a list of [cell tags] that the tag | ||
currently depends on. This list can change over time, so it must not be | ||
cached. | ||
debugging features of Starbeam. _This property is undefined in production_ | ||
- A `dependencies` property. This is a function that, when called, returns a | ||
list of the cell tags that the current tag depends on. If the value that the | ||
tag represents is an uninitialized formula, this property is `UNINITIALIZED`. | ||
@@ -57,34 +53,24 @@ ## The Tags | ||
When a cell tag represents a _frozen value_, its `dependencies` method returns | ||
an empty list. A frozen value will not change in the future. | ||
When a cell tag represents a _mutable value_, its `dependencies` method returns | ||
a list containing the cell tag itself. | ||
In addition to the fundamental properties, they have the following additional | ||
properties: | ||
property: | ||
- An `isFrozen()` method. This method may return `true` if the value the tag | ||
represents will not change in the future. Once a cell tag becomes frozen, | ||
subscribers to the tag are free to unsubscribe. | ||
- A `freeze()` method. This method marks the tag as frozen (which means that | ||
`isFrozen()` will return true after this point). Freezing a tag does not | ||
increment its revision counter: if a consumer of the tag is up-to-date, | ||
freezing the tag does not require the consumer to handle changes to its value. | ||
- An `update()` method. This method indicates that the tag's underlying storage | ||
has changed. Calling this method updates the `lastUpdated` property to the | ||
current timestamp. | ||
- A `lastUpdated` property. This property is the revision of the cell tag. It | ||
is updated whenever the cell tag is updated. | ||
A cell tag's `dependencies()` are: | ||
- empty when the cell is frozen | ||
- the cell itself when the cell is not frozen | ||
- empty when the cell tag represents a _frozen value_. A frozen value will not | ||
change in the future. | ||
- an array containing the cell tag itself when the cell tag represents a | ||
_mutable value_. | ||
### Static Tags | ||
A static value (i.e. a value that will never change during its entire lifetime) | ||
is modelled as a frozen cell (its dependencies will always be empty). | ||
A static tag represents a value that can never change. Unlike a frozen cell tag, | ||
which represents data that may have changed in the past, a static tag represents | ||
data that has always been the same. | ||
There is never any reason to subscribe to a static tag, and they are never | ||
included in a tag's `dependendencies()` list. | ||
They primarily exist to model parameters that could either be `T` or | ||
`Reactive<T>`, where a `T` parameter is coerced into `Static<T>` with a static | ||
tag. | ||
### Formula Tags | ||
@@ -95,4 +81,2 @@ | ||
Its `lastUpdated` property is the latest revision of its current children. | ||
Its `dependencies()` method returns a list of the cells that its current children | ||
@@ -102,22 +86,12 @@ depend on. This is a recursive process that returns a flattened list of the cell | ||
In addition to the fundamental properties, a formula tag has the following | ||
additional properties: | ||
When the formula tag represents an _uninitialized formula_, its `dependencies` | ||
property is `undefined` (and not a function). | ||
- A `tdz` ("temporal dead zone") property. This property is true when the | ||
computation that this tag represents has not yet been evaluated. Subscribing | ||
to a formula tag in the `tdz` state is semantically invalid. Attempting to do | ||
so indicates a mistake in the implementation. | ||
- An `unsetTDZ()` method, which sets the `tdz` property to `false`. | ||
> It is possible to render an uninitialized formula. In this situation, the | ||
> renderer will receive a readiness notification. This may make sense under | ||
> certain circumstances (and is used in practice in Starbeam renderers). | ||
> | ||
> However, rendering an uninitialized formula bears some thought about what it | ||
> means to render an uninitialized value. | ||
### Delegate Tags | ||
A delegate tag represents a reactive computation whose component tags _will not | ||
change_ over the lifetime of the tag. | ||
It exists to make it possible to create abstractions around underlying reactive | ||
values, but allow subscribers to those abstractions to subscribe directly to the | ||
component tags. | ||
Semantically, you can think of a delegate tag as a special kind of formula tag. | ||
## Tag Composition | ||
@@ -124,0 +98,0 @@ |
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
No License Found
License(Experimental) License information could not be found.
Found 1 instance in 1 package
49638
11
0
282
4
160
1
+ Addedinspect-utils@^1.0.1
+ Added@domtree/any@0.9.3(transitive)
+ Added@domtree/browser@0.9.3(transitive)
+ Added@domtree/interface@0.9.3(transitive)
+ Added@domtree/minimal@0.9.3(transitive)
+ Added@starbeam/core-utils@0.8.10-unstable.bca55c9(transitive)
+ Added@starbeam/interfaces@0.8.10-unstable.bca55c9(transitive)
+ Added@starbeam/shared@1.3.8-unstable.bca55c9(transitive)
+ Addedinspect-utils@1.0.1(transitive)
- Removed@starbeam/core-utils@0.8.10-unstable.aeb2ad9(transitive)
- Removed@starbeam/interfaces@0.8.10-unstable.aeb2ad9(transitive)
- Removed@starbeam/shared@1.3.8-unstable.aeb2ad9(transitive)