Some long-needed renaming and consolidation (#90)Co-authored-by: Null…

…VoxPopuli <[email protected]>

This commit holistic renames, consolidates, and cleans up internal
concepts.

* Rename "internal" concepts to Tag and Tagged
* Simplify and improve the notion of subscriptions

## Created new packages

- @starbeam/runtime
- @starbeam/tags
- @starbeam/reactive
- @starbeam/resource
- @starbeam/service

### Created `@starbeam/tags`

Previously, the implementation of tags lived in `TIMELINE`, which has a
whole bunch of other unrelated stuff. So the abstraction went directly
from the interfaces defined in `@starbeam/interfaces` to the full-fledged
timeline definition in `@starbeam/timeline`.

This created an awkward situation where tags ought to have been real
objects (so they can share utility code), but we had utility function
instead that worked with the interfaces to avoid dragging all of
TIMELINE into the definition of tags.

This commit separates tags into their own package which clearly defines
the semantics of tags and provides concrete implementations for them.

This simplifies the code considerably, and also more clearly
communicates what tags are for.

## Notes from the implementation of resources

The third attempt to reimplement resource on top of the new primitives worked
beautifully.

It supports `ResourceList`, but where the previous implementation worked
by implicitly adopting resources across runs, the new implementation of
`ResourceList` manages the lifetimes of its child resources explicitly.

The code is nearly as compact, in part because the new resource
implementation is more honest about separating entire-resource state
from per-run state.

The new resource primitive adds support for resource metadata (state
that lives for the entire lifetime of the resource and can be used for
cross-run state).

---
Co-authored-by: NullVoxPopuli <[email protected]>

.config/tsconfig/tsconfig.shared.json

@@ -4,7 +4,7 @@
 
     "target": "ESNext",
     "module": "ESNext",
-    "moduleResolution": "Node",
+    "moduleResolution": "bundler",
 
     "declaration": true,
     "declarationMap": true,
@@ -17,15 +17,14 @@
     "noImplicitOverride": true,
 
     "isolatedModules": true,
-    "preserveValueImports": true,
     "skipLibCheck": true,
     "skipDefaultLibCheck": true,
 
     "esModuleInterop": true,
     "allowSyntheticDefaultImports": true,
 
     "useDefineForClassFields": true,
-    "importsNotUsedAsValues": "error",
+    "verbatimModuleSyntax": true,
 
     "resolveJsonModule": true,
 

.github/workflows/ci.yml

@@ -15,37 +15,15 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - name: "Setup node and install dependencies"
-        uses: ./.github/actions/setup-node-and-install
-        # currently not used - as tests, lints, etc are all top-level commands / projects
-        # if we were to make each workspace isolated, we'd first need to copy tsc/eslint/vitest
-        # configs into each package -- but that would be slower than what today's setup is.
-      - id: set-matrix
-        name: "Find workspaces"
-        # generates a list of root-relative paths to each workspace
-        #
-        # the pipes line-by-line:
-        #   Remove version information
-        #   Remove the current directory
-        #   Remove empty lines
-        #   Remove leading slashes
-        run: |
-          root_of_repo=$(git rev-parse --show-toplevel)
-          workspaces=$(pnpm ls -r --depth -1 --long --parseable \
-            | cut -f1 -d':' \
-            | sed "s~$root_of_repo~~g" \
-            | sed '/^[[:space:]]*$/d' \
-            | sed 's~^/~~g')
-          echo "::set-output name=matrix::$(echo $workspaces)"
+      - uses: NullVoxPopuli/action-setup-pnpm@v2
 
   test:
     name: "Tests"
     runs-on: "ubuntu-latest"
     needs: ["install_dependencies"]
     steps:
       - uses: actions/checkout@v2
-      - name: "Setup node and install dependencies"
-        uses: ./.github/actions/setup-node-and-install
+      - uses: NullVoxPopuli/action-setup-pnpm@v2
       - run: pnpm ci:specs
 
   test_prod:
@@ -54,8 +32,7 @@ jobs:
     needs: ["install_dependencies"]
     steps:
       - uses: actions/checkout@v2
-      - name: "Setup node and install dependencies"
-        uses: ./.github/actions/setup-node-and-install
+      - uses: NullVoxPopuli/action-setup-pnpm@v2
       - run: pnpm ci:prod
 
   typecheck:
@@ -64,8 +41,7 @@ jobs:
     needs: ["install_dependencies"]
     steps:
       - uses: actions/checkout@v2
-      - name: "Setup node and install dependencies"
-        uses: ./.github/actions/setup-node-and-install
+      - uses: NullVoxPopuli/action-setup-pnpm@v2
       - run: pnpm ci:types
 
   lint:
@@ -74,8 +50,7 @@ jobs:
     needs: ["install_dependencies"]
     steps:
       - uses: actions/checkout@v2
-      - name: "Setup node and install dependencies"
-        uses: ./.github/actions/setup-node-and-install
+      - uses: NullVoxPopuli/action-setup-pnpm@v2
       - run: pnpm ci:lint
 
   release:
@@ -85,5 +60,4 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - name: "Setup node and install dependencies"
-        uses: ./.github/actions/setup-node-and-install
+      - uses: NullVoxPopuli/action-setup-pnpm@v2

.vscode/settings.json

@@ -24,10 +24,10 @@
 
   "eslint.codeActionsOnSave.mode": "all",
   "eslint.enable": true,
-  "eslint.format.enable": true,
   "eslint.lintTask.enable": true,
   "eslint.lintTask.options": "--cache -c ./.eslintrc.json --max-warnings=0 \"**/*.ts\" \"**/*.tsx\" \"**/*.json\"",
   "eslint.onIgnoredFiles": "warn",
+  "eslint.problems.shortenToSingleLine": true,
   "eslint.quiet": false,
   "eslint.validate": [
     "javascript",
@@ -39,7 +39,7 @@
     "html"
   ],
 
-  "explorer.excludeGitIgnore": false,
+  "explorer.excludeGitIgnore": true,
   "explorer.fileNesting.patterns": {
     "*.cjs": "${capture}.cjs.map, ${capture}.min.cjs, ${capture}.d.cts, ${capture}.d.cts.map",
     "*.js": "${capture}.js.map, ${capture}.min.js, ${capture}.d.ts, ${capture}.d.ts.map",
@@ -68,13 +68,17 @@
       "url": "https://json.schemastore.org/chrome-manifest"
     }
   ],
+  "npm-scripts.showStartNotification": false,
+  "rewrap.autoWrap.enabled": true,
+  "rewrap.reformat": true,
+  "rewrap.wrappingColumn": 80,
 
   "search.exclude": {
     "**/CHANGELOG.md": true,
     "pnpm-lock.yaml": true
   },
-
   "testing.automaticallyOpenPeekView": "never",
+  "typescript.experimental.tsserver.web.enableProjectWideIntellisense": false,
 
   "typescript.preferences.importModuleSpecifier": "project-relative",
   "typescript.preferences.importModuleSpecifierEnding": "js",

@types/ansicolor/.eslintrc.json

@@ -0,0 +1,12 @@
+{
+  "root": false,
+  "overrides": [
+    {
+      "extends": ["plugin:@starbeam/commonjs"],
+      "files": ["index.d.ts", "src/**/*.d.ts"],
+      "parserOptions": {
+        "project": "@types/ansicolor/tsconfig.json"
+      }
+    }
+  ]
+}

@types/ansicolor/index.d.ts

@@ -0,0 +1,48 @@
+type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
+
+type Colors =
+  | "Black"
+  | "Red"
+  | "Green"
+  | "Yellow"
+  | "Blue"
+  | "Magenta"
+  | "Cyan"
+  | "White"
+  | "Default";
+
+type Styles = "bright" | "dim" | "italic" | "underline" | "inverse";
+
+type Bg = `bg${"Bright" | ""}${Colors}`;
+
+type BgColor = Expand<{
+  [key in Colors]: Color;
+}>;
+
+type FgColor = Expand<{
+  bright: Color;
+  dim: Color;
+  italic: Color;
+  underline: Color;
+  inverse: Color;
+  dim: Color;
+  magenta: Color;
+  black: Color;
+  red: Color;
+  green: Color;
+  yellow: Color;
+  blue: Color;
+  magenta: Color;
+  cyan: Color;
+  white: Color;
+  default: Color;
+}>;
+
+interface Methods {
+  strip: Color;
+}
+
+export type Color = Methods & BgColor & FgColor & ((text: string) => string);
+
+const DEFAULT: Color;
+export default DEFAULT;

@types/ansicolor/package.json

@@ -0,0 +1,31 @@
+{
+  "private": true,
+  "name": "@types/ansicolor",
+  "version": "1.0.0",
+  "type": "module",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts"
+      }
+    },
+    "types": "dist/index.d.ts"
+  },
+  "starbeam": {
+    "source": "d.ts",
+    "type": "library:upstream-types"
+  },
+  "scripts": {
+    "test:lint": "eslint",
+    "test:types": "tsc -b"
+  },
+  "devDependencies": {
+    "@types/node": "*"
+  }
+}

@types/ansicolor/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../.config/tsconfig/tsconfig.shared.json",
+  "compilerOptions": {
+    "declarationMap": true,
+    "declarationDir": "../../dist/types",
+    "declaration": true,
+    "outDir": "../../dist/packages",
+    "composite": true,
+    "types": ["../../packages/env", "node"]
+  },
+  "exclude": ["dist/**/*"]
+}

@types/rollup-plugin-polyfill-node/tsconfig.json

@@ -2,9 +2,9 @@
   "extends": "../../.config/tsconfig/tsconfig.shared.json",
   "compilerOptions": {
     "declarationMap": true,
-    "declarationDir": "../../../dist/types",
+    "declarationDir": "../../dist/types",
     "declaration": true,
-    "outDir": "../../../dist/packages",
+    "outDir": "../../dist/packages",
     "composite": true,
     "types": ["../../packages/env"]
   },

demos/preact-hello-world/package.json

@@ -36,9 +36,9 @@
     "test:types": "tsc -b"
   },
   "dependencies": {
-    "@starbeam/js": "workspace:^",
+    "@starbeam/collections": "workspace:^",
     "@starbeam/preact": "workspace:^",
-    "@starbeam/timeline": "workspace:^",
+    "@starbeam/runtime": "workspace:^",
     "@starbeam/universal": "workspace:^",
     "preact": "^10.11.3",
     "purecss": "3.0.0"

demos/preact-hello-world/src/components/App.tsx

@@ -1,13 +1,13 @@
-import { create, createCell, use } from "@starbeam/preact";
-import type { Factory, ResourceBlueprint } from "@starbeam/universal";
-import { Cell, Resource, service } from "@starbeam/universal";
+import { createCell, service, use } from "@starbeam/preact";
+import type { ResourceBlueprint } from "@starbeam/universal";
+import { Cell, Resource } from "@starbeam/universal";
 import type { JSX } from "preact";
 import { useState } from "preact/hooks";
 
 import Card from "./Card.jsx";
 
 export default function App(): JSX.Element {
-  const counter = create(Count);
+  const counter = use(Count);
 
   const [showChild, setShowChild] = useState(true);
   const cell = createCell(0, "cell");
@@ -112,7 +112,7 @@ function UsingCounterService({
   Service,
 }: {
   name: string;
-  Service: Factory<CounterData>;
+  Service: ResourceBlueprint<CounterData>;
 }): JSX.Element {
   const counter = service(Service);
 
@@ -157,7 +157,7 @@ interface CounterData {
   increment: () => void;
 }
 
-function Count(): CounterData {
+const Count = Resource(() => {
   const count = Cell(0, "data count");
 
   return {
@@ -168,7 +168,7 @@ function Count(): CounterData {
       count.current++;
     },
   };
-}
+});
 
 function CounterWithCleanup(
   status: Cell<string> = Cell("new")

demos/preact-hello-world/src/components/Card.tsx

@@ -1,15 +1,14 @@
 import "preact";
 
-import type { ComponentChildren } from "preact";
-import type { JSXInternal } from "preact/src/jsx.js";
+import type { ComponentChildren, JSX } from "preact";
 
 export default function Card({
   children,
   class: className,
 }: {
   children?: ComponentChildren;
   class?: string;
-}): JSXInternal.Element {
+}): JSX.Element {
   const classes = ["card"];
   if (className) classes.push(className);
   return <div class={classes.join(" ")}>{children}</div>;

demos/preact-hello-world/src/index.tsx

@@ -3,10 +3,10 @@ import "preact/hooks";
 import { setup } from "@starbeam/preact";
 import { options, render } from "preact";
 
-setup(options);
-
 import App from "./components/App.jsx";
 
+setup(options);
+
 const container = document.querySelector("#root");
 
 if (!container) {

demos/preact/package.json

@@ -36,8 +36,11 @@
     "test:types": "tsc -b"
   },
   "dependencies": {
-    "@starbeam/js": "workspace:^",
+    "@starbeam/collections": "workspace:^",
+    "@starbeam/interfaces": "workspace:^",
     "@starbeam/preact": "workspace:^",
+    "@starbeam/reactive": "workspace:^",
+    "@starbeam/resource": "workspace:^",
     "@starbeam/universal": "workspace:^",
     "preact": "^10.11.3",
     "purecss": "^3.0.0"

demos/preact/src/components/db/Db-1.tsx

@@ -1,4 +1,4 @@
-import { object } from "@starbeam/js";
+import { object } from "@starbeam/collections";
 import { create } from "@starbeam/preact";
 import type { JSX } from "preact/jsx-runtime";
 

demos/preact/src/components/db/Db-2.tsx

@@ -1,5 +1,5 @@
 
-import { reactive } from "@starbeam/js";
+import { reactive } from "@starbeam/collections";
 import { create } from "@starbeam/preact";
 import type { JSX } from "preact/jsx-runtime";