@starbeam/shared - npm Package Compare versions

Comparing version 1.3.8-unstable.398c1bd to 1.3.8-unstable.3e1af4d

index.ts

@@ -1,4 +0,13 @@
-export { COORDINATION, TAG, UNINITIALIZED } from "./src/constants.js";
+export { TAG, UNINITIALIZED } from "./src/constants.js";
 export { getID } from "./src/id.js";
+export {
+  finalize,
+  isFinalized,
+  linkToFinalizationScope,
+  mountFinalizationScope,
+  onFinalize,
+  pushFinalizationScope,
+} from "./src/lifetimes.js";
 export { bump, now } from "./src/now.js";
 export { consume, start } from "./src/stack.js";
+export { testing } from "./src/testing.js";

package.json

 {
   "name": "@starbeam/shared",
-  "version": "1.3.8-unstable.398c1bd",
+  "type": "module",
+  "version": "1.3.8-unstable.3e1af4d",
   "description": "A package that facilitates having multiple copies of Starbeam in a single process that interoperate with each other",
-  "type": "module",
-  "main": "index.ts",
-  "types": "index.ts",
+  "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",
+  "devDependencies": {
+    "@starbeam-dev/compile": "^1.0.2",
+    "@starbeam-dev/eslint-plugin": "^1.0.4",
+    "rollup": "^4.0.2"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
   "scripts": {
-    "test:lint": "eslint \"index.ts\" \"src/**/*.ts\"",
-    "test:specs": "vitest --run",
+    "build": "rollup -c",
+    "test:lint": "eslint . --max-warnings 0",
+    "test:specs": "vitest --run --pool forks",
     "test:types": "tsc -b"
-  },
-  "devDependencies": {
-    "@starbeam-dev/build-support": "workspace:*",
-    "rollup": "^3.20.6"
   }
-}
+}

README.md

@@ -1,15 +0,90 @@
-This package provides an extremely stable API for getting:
+# `@starbeam/shared`
 
-- The current timestamp as a number
-- The value of the `UNINITIALIZED` symbol
+**Unless you are very interested in the stability strategy of Starbeam, you don't
+need to understand how this package works.**
 
-Apps shouldn't use the exports of this dependency directly. Instead, separating the most fundamental
-parts of Starbeam's composition into a separate package allows two versions of Starbeam to coexist
-in the same process and **to share reactivity between them**.
+---
 
-In other words, if you access a Cell from version 1 of Starbeam in the context of a formula
-created in version 2 of Starbeam, updating the cell will invalidate the formula.
+This package is designed to make it possible for multiple copies of Starbeam to
+interact with each other in a single process.
 
-This package uses `Symbol.for` to ensure that only a single copy of the fundamental symbols and
-constants exists in a single process. As a result, it is not necessary to install this package as a
-peer dependency.
+> For example, this means that:
+>
+> - if one copy of Starbeam creates a formula
+> - and the formula read the value of a cell from another copy of Starbeam
+> - then updating the cell will invalidate the formula
+
+## How it Works
+
+It accomplishes this by storing a handful of very stable Starbeam fundamentals
+in a single global symbol (`Symbol.for("starbeam.COORDINATION")`).
+
+The first access to any of `@starbeam/shared`'s exports (from any copy of
+Starbeam) instantiates the values in that symbol. Future accesses of the exports
+use that already instantiated value.
+
+> This package uses `Symbol.for` to ensure that only a single copy of the
+> fundamental symbols and constants exists in a single process. As a result, **it
+> is not necessary to install this package as a peer dependency**.
+
+## Starbeam Fundamentals
+
+<dl>
+  <dt><code>now()</code></dt>
+  <dd>Returns the current timestamp as a number.</dd>
+  <dt><code>bump()</code></dt>
+  <dd>Increment the current timestamp and return the new one.</dd>
+  <dt><code>start()</code></dt>
+  <dd>Start a new tracking frame. This function returns a function that, when called, finalizes the tracking frame. The finalization function returns a list of the cell tags that were consumed during the duration of the tracking frame.</dd>
+  <dt><code>consume(tag)</code></dt>
+  <dd>Consume a tag.</dd>
+  <dt><code>getId()</code></dt>
+  <dd>Returns a unique, deterministic identifier as a string or number. This is useful to create primitive identifiers that are guaranteed to be unique even if multiple copies of Starbeam exist in a single process.</dd>
+  <dt><code>TAG</code></dt>
+  <dd>The value of the `TAG` symbol. A reactive value's tag is stored in this property.</dd>
+  <dt><code>UNINITIALIZED</code></dt>
+  <dd>A special value representing an uninitialized value. This is sometimes necessary to differentiate between <code>undefined</code> as an actual user value and an internal uninitialized state.</dd>
+</dl>
+
+## Stability
+
+The goal of this package is to provide a place for the most primitive
+representation of Starbeam fundamentals. It is designed to be as stable as
+possible, so that the implementations of tags and reactive values from multiple
+different major versions of Starbeam can interoperate.
+
+We expect this package to remain at `1.x` for the foreseeable future.
+
+If we need to make breaking changes to this package, that will also make
+versions of Starbeam that depend on `1.x` incompatible with versions of Starbeam
+that depend on `2.x`. As a result, we intend to try as hard as possible to avoid
+strictly breaking changes.
+
+One consequence of this design goal is that the functions in this package take
+and return simple TypeScript types. For example, timestamps are represented as
+numbers and cell tags are just `unknown`.
+
+In practice, interoperability between Starbeam versions will also require
+stability in the fundamental protocol of cell tags. This basically means that
+the fundamental interface for tags is:
+
+```ts
+interface CellTag {
+  readonly lastUpdated: number;
+  readonly dependencies: () => CellTag[];
+}
+
+interface FormulaTag {
+  readonly dependencies: undefined | (() => CellTag[]);
+}
+
+type Tag = CellTag | FormulaTag;
+```
+
+Because TypeScript frequently makes breaking changes, adding these fundamental
+types to this package as part of its API is still a work in progress.
+
+However, the description of the fundamental tag types is intended to document
+the intended stability of the `Tag` types in Starbeam, which means that the
+implementation of tags in other parts of Starbeam will only change if
+`@starbeam/shared` has a major version bump.

New alerts

License Policy Violation

License

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

Package 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

Fixed alerts

License Policy Violation

License

This 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

Improved metrics

Total package byte prevSize

93458

increased by744.02%

Number of low license alerts

0

decreased by-100%

Lines of code

687

increased by185.06%

Number of lines in readme file

91

increased by468.75%

Worsened metrics

Dev dependency count

3

increased by50%

Number of package files

11

decreased by-38.89%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes