@backtickjs/core 0.2.1 → 0.2.3

package/README.md

@@ -58,36 +58,40 @@ import { greet } from "my-native-module" with { backtick: "client" };
 
 The package must be installed where the server's file finds it, for its types and its version. The client must provide it, and the server must list it in the bundler's `modules` at that version or a later one of the same major. The compiler writes each name as what `createImport({ name, from, version })` makes, which a hand-written import can call too.
 
+To draw for clients on two majors of a package, install both, one under an alias: `"acme-ui-2": "npm:acme-ui@2"`. An import from either is of `acme-ui`, the module clients provide, typed against its own version; `supports`, in a server component, picks the one the client can run:
+
+```ts
+import { Button } from "acme-ui" with { backtick: "client" };
+import { Button as Button2 } from "acme-ui-2" with { backtick: "client" };
+
+function Save() {
+  return supports("acme-ui", "^2.0.0")
+    ? cs`<$Button2 tone="primary">Save</$Button2>`
+    : cs`<$Button variant="primary">Save</$Button>`;
+}
+```
+
 ## Every build in users' hands
 
 A store build carries the modules it was built with, at their versions, for as long as it's installed, while your server moves on. Each build sends the modules it carries, and the server bundles its screens for exactly those: there's nothing to record before a build ships, and any version of your server can draw for any build.
 
 1. **The app's module map** offers what screens may require, each from a package in `package.json`'s dependencies. A platform that differs gets its own file, as Metro picks files: `client/moduleMap.web.ts` for the web.
 
-2. **The app's config carries its packages' versions.** `installedPackages`, from `@backtickjs/core/node`, reads the installed version of each of the app's dependencies from `node_modules`. In an Expo app, `app.config.ts` puts them in the config, which Expo embeds in the app:
+2. **The app's build records its installed packages.** `installedPackages`, from `@backtickjs/core/node`, reads the installed version of each of the app's dependencies from `node_modules`, and the build embeds them in the app. In an Expo app, the config plugin from [`@backtickjs/expo`](https://github.com/backtickjs/backtick/tree/main/packages/expo) does it:
 
-   ```ts
-   // app.config.ts
-   import { installedPackages } from "@backtickjs/core/node";
-   import type { ConfigContext, ExpoConfig } from "expo/config";
-
-   export default ({ config, projectRoot }: ConfigContext): ExpoConfig => ({
-     ...(config as ExpoConfig),
-     extra: {
-       ...config.extra,
-       backtick: { packages: installedPackages(projectRoot) },
-     },
-   });
+   ```json
+   // app.json
+   { "expo": { "plugins": ["@backtickjs/expo"] } }
    ```
 
-3. **The app sends its modules** however it reaches its server: a header, a GraphQL variable. `modulesOf` gives each module in the map its package's version, and throws as the app starts without them, or for a module from a package that isn't a dependency:
+3. **The app sends its modules** however it reaches its server: a header, a GraphQL variable. `modulesOf` gives each module in the map its package's version, and throws as the app starts for a module from a package that isn't a dependency:
 
    ```ts
    import { modulesOf } from "@backtickjs/core";
+   import { getBacktickExtra } from "@backtickjs/expo";
 
-   const modules = JSON.stringify(
-     modulesOf(moduleMap, Constants.expoConfig?.extra?.backtick?.packages),
-   );
+   const { installedPackages } = getBacktickExtra(Constants.expoConfig);
+   const modules = JSON.stringify(modulesOf(moduleMap, installedPackages));
    fetch(url, { headers: { "x-backtick-modules": modules } });
    ```
 
@@ -98,7 +102,7 @@ A store build carries the modules it was built with, at their versions, for as l
    const bundle = await bundler.build({ input, modules });
    ```
 
-   The bundler refuses modules that aren't `{ "specifier": "version" }`, and a screen that imports a module the build doesn't carry, or at a version it can't run. To draw differently for builds that lack a module, or to ask old ones to update, check with `supports` from [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler): `supports(modules, "react-native", ">=0.86")`.
+   The bundler refuses modules that aren't `{ "specifier": "version" }`, and a screen that imports a module the build doesn't carry, or at a version it can't run. To draw differently for builds that lack a module, or to ask old ones to update, check with `supports` from [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler), in a server component: `supports("react-native", ">=0.86")`.
 
 In development, a reload keeps the app config the app was opened with, and its versions with it: after upgrading a package, close the app and open it again.
 
@@ -116,8 +120,8 @@ A test draws a screen with a module map of its own, stand-ins included; its modu
 - `Bundle<T>`: a bundle's code, branded with what it runs to. `bundler.build(…).generate(…)` writes one.
 - `execRoot(bundle, moduleMap)`, from `@backtickjs/core/cjs`: in a React Native app, runs the CommonJS bundle it starts from to its value, as a promise, with `require` answered from `moduleMap`, a `ModuleMap`: the modules the app provides, by specifier.
 - `execRoot(bundle)`, from `@backtickjs/core/es`: in a web page, imports the ES bundle it starts from and resolves to its value, the page's import map answering its imports. Each format has its own entry, so a React Native app's bundler never reads the ES one's `import()`.
-- `modulesOf(moduleMap, packages)`: the modules `moduleMap`, a `ModuleMap`, offers, each at its package's version in `packages`, for the app to send its server.
-- `installedPackages(projectRoot)`, from `@backtickjs/core/node`: the installed version of each of the app's dependencies, read from `node_modules`. Node only.
+- `modulesOf(moduleMap, installedPackages)`: the modules `moduleMap`, a `ModuleMap`, offers, each at its package's version in `installedPackages`, for the app to send its server.
+- `installedPackages(projectRoot)`, from `@backtickjs/core/node`: the installed version of each of the app's dependencies, read from `node_modules` as Metro finds packages by default. A `metro.config.js` that aliases or redirects packages needs its own versions. Node only.
 - `exec`: in a script, `$exec(bundle)` runs another bundle as the script's own was run, with the same modules, to a promise of its value.
 - `isClientExec`, `ClientExec`: its check and type.
 - `SplicesAs<T>`: `T` as a splice checks it, member by member. Used by the bundler to check its input.

package/dist/modulesOf.d.ts

@@ -15,16 +15,13 @@
  */
 export type ModuleMap = Readonly<Record<string, unknown>>;
 /**
- * The modules `moduleMap` offers, each at the version in `packages` of the
- * package it comes from: what the app sends however it reaches its server, a
- * header, a GraphQL variable, for the server to bundle screens it can run.
- * An Expo app passes them from its config, where `app.config.ts` puts
- * `installedPackages(projectRoot)`. Throws as the app starts without them, or
- * for a module from a package that isn't a dependency.
+ * The modules `moduleMap` offers, each at the version in `installedPackages`
+ * of the package it comes from: what the app sends however it reaches its
+ * server, a header, a GraphQL variable, for the server to bundle screens it
+ * can run. The app's build records them, with `installedPackages` from
+ * `@backtickjs/core/node`. Throws as the app starts for a module from a
+ * package that isn't a dependency.
  *
- *     const modules = modulesOf(
- *       moduleMap,
- *       Constants.expoConfig?.extra?.backtick?.packages,
- *     );
+ *     const modules = modulesOf(moduleMap, installedPackages);
  */
-export declare function modulesOf(moduleMap: ModuleMap, packages: Readonly<Record<string, string>> | null | undefined): Record<string, string>;
+export declare function modulesOf(moduleMap: ModuleMap, installedPackages: Readonly<Record<string, string>>): Record<string, string>;

package/dist/modulesOf.js

@@ -4,24 +4,18 @@ function packageOf(specifier) {
     return segments.slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
 }
 /**
- * The modules `moduleMap` offers, each at the version in `packages` of the
- * package it comes from: what the app sends however it reaches its server, a
- * header, a GraphQL variable, for the server to bundle screens it can run.
- * An Expo app passes them from its config, where `app.config.ts` puts
- * `installedPackages(projectRoot)`. Throws as the app starts without them, or
- * for a module from a package that isn't a dependency.
+ * The modules `moduleMap` offers, each at the version in `installedPackages`
+ * of the package it comes from: what the app sends however it reaches its
+ * server, a header, a GraphQL variable, for the server to bundle screens it
+ * can run. The app's build records them, with `installedPackages` from
+ * `@backtickjs/core/node`. Throws as the app starts for a module from a
+ * package that isn't a dependency.
  *
- *     const modules = modulesOf(
- *       moduleMap,
- *       Constants.expoConfig?.extra?.backtick?.packages,
- *     );
+ *     const modules = modulesOf(moduleMap, installedPackages);
  */
-export function modulesOf(moduleMap, packages) {
-    if (packages == null) {
-        throw new Error("No packages: does app.config.ts put installedPackages(projectRoot) in the config's extra?");
-    }
+export function modulesOf(moduleMap, installedPackages) {
     return Object.fromEntries(Object.keys(moduleMap).map((specifier) => {
-        const version = packages[packageOf(specifier)];
+        const version = installedPackages[packageOf(specifier)];
         if (version === undefined) {
             throw new Error(`The module map offers ${JSON.stringify(specifier)}, but ${packageOf(specifier)} isn't in package.json's dependencies.`);
         }

package/dist/modulesOf.js.map

@@ -1 +1 @@
-{"version":3,"file":"modulesOf.js","sourceRoot":"","sources":["../src/modulesOf.ts"],"names":[],"mappings":"AAiBA,yEAAyE;AACzE,SAAS,SAAS,CAAC,SAAiB;IAClC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CACvB,SAAoB,EACpB,QAA6D;IAE7D,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;QACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,SAAS,SAAS,CAAC,SAAS,CAAC,wCAAwC,CACxH,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"modulesOf.js","sourceRoot":"","sources":["../src/modulesOf.ts"],"names":[],"mappings":"AAiBA,yEAAyE;AACzE,SAAS,SAAS,CAAC,SAAiB;IAClC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CACvB,SAAoB,EACpB,iBAAmD;IAEnD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;QACvC,MAAM,OAAO,GAAG,iBAAiB,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;QACxD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,SAAS,SAAS,CAAC,SAAS,CAAC,wCAAwC,CACxH,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/node.d.ts

@@ -1,14 +1,9 @@
 /**
  * The installed version of each of the app's dependencies, at `projectRoot`:
- * what a build made from it now carries there, for `modulesOf`. Node only: an
- * Expo app calls it from `app.config.ts`, and passes it on in the config.
- *
- *     export default ({ config, projectRoot }: ConfigContext) => ({
- *       ...config,
- *       extra: {
- *         ...config.extra,
- *         backtick: { packages: installedPackages(projectRoot) },
- *       },
- *     });
+ * what a build made from it now carries there, for `modulesOf`. Node only:
+ * the app's build calls it, and embeds what it answers in the app.
+ * Packages are found as Metro finds them by default, in `node_modules` here
+ * or above: a `metro.config.js` that aliases or redirects them needs its own
+ * versions.
  */
 export declare function installedPackages(projectRoot: string): Record<string, string>;

package/dist/node.js

@@ -14,16 +14,11 @@ function installed(projectRoot, name) {
 }
 /**
  * The installed version of each of the app's dependencies, at `projectRoot`:
- * what a build made from it now carries there, for `modulesOf`. Node only: an
- * Expo app calls it from `app.config.ts`, and passes it on in the config.
- *
- *     export default ({ config, projectRoot }: ConfigContext) => ({
- *       ...config,
- *       extra: {
- *         ...config.extra,
- *         backtick: { packages: installedPackages(projectRoot) },
- *       },
- *     });
+ * what a build made from it now carries there, for `modulesOf`. Node only:
+ * the app's build calls it, and embeds what it answers in the app.
+ * Packages are found as Metro finds them by default, in `node_modules` here
+ * or above: a `metro.config.js` that aliases or redirects them needs its own
+ * versions.
  */
 export function installedPackages(projectRoot) {
     const { dependencies = {} } = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));

package/dist/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,2EAA2E;AAC3E,2EAA2E;AAC3E,SAAS,SAAS,CAAC,WAAmB,EAAE,IAAY;IAClD,KAAK,IAAI,SAAS,GAAG,WAAW,GAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACnE,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAClC,IAAI,OAAO,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,GAAG,WAAW,KAAK,IAAI,kBAAkB,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,MAAM,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,CACtC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CACX,CAAC;IAC/C,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACtC,IAAI;QAEF,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAG9D,CAAC,OAAO;KACV,CAAC,CACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,2EAA2E;AAC3E,2EAA2E;AAC3E,SAAS,SAAS,CAAC,WAAmB,EAAE,IAAY;IAClD,KAAK,IAAI,SAAS,GAAG,WAAW,GAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACnE,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAClC,IAAI,OAAO,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,GAAG,WAAW,KAAK,IAAI,kBAAkB,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,MAAM,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,CACtC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CACX,CAAC;IAC/C,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACtC,IAAI;QAEF,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAG9D,CAAC,OAAO;KACV,CAAC,CACH,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtickjs/core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "The cs tag for Backtick client scripts, and the types for the values that cross from server to client",
   "keywords": [
     "backtick",

package/src/modulesOf.ts

@@ -22,30 +22,22 @@ function packageOf(specifier: string): string {
 }
 
 /**
- * The modules `moduleMap` offers, each at the version in `packages` of the
- * package it comes from: what the app sends however it reaches its server, a
- * header, a GraphQL variable, for the server to bundle screens it can run.
- * An Expo app passes them from its config, where `app.config.ts` puts
- * `installedPackages(projectRoot)`. Throws as the app starts without them, or
- * for a module from a package that isn't a dependency.
+ * The modules `moduleMap` offers, each at the version in `installedPackages`
+ * of the package it comes from: what the app sends however it reaches its
+ * server, a header, a GraphQL variable, for the server to bundle screens it
+ * can run. The app's build records them, with `installedPackages` from
+ * `@backtickjs/core/node`. Throws as the app starts for a module from a
+ * package that isn't a dependency.
  *
- *     const modules = modulesOf(
- *       moduleMap,
- *       Constants.expoConfig?.extra?.backtick?.packages,
- *     );
+ *     const modules = modulesOf(moduleMap, installedPackages);
  */
 export function modulesOf(
   moduleMap: ModuleMap,
-  packages: Readonly<Record<string, string>> | null | undefined,
+  installedPackages: Readonly<Record<string, string>>,
 ): Record<string, string> {
-  if (packages == null) {
-    throw new Error(
-      "No packages: does app.config.ts put installedPackages(projectRoot) in the config's extra?",
-    );
-  }
   return Object.fromEntries(
     Object.keys(moduleMap).map((specifier) => {
-      const version = packages[packageOf(specifier)];
+      const version = installedPackages[packageOf(specifier)];
       if (version === undefined) {
         throw new Error(
           `The module map offers ${JSON.stringify(specifier)}, but ${packageOf(specifier)} isn't in package.json's dependencies.`,

package/src/node.ts

@@ -15,16 +15,11 @@ function installed(projectRoot: string, name: string): string {
 
 /**
  * The installed version of each of the app's dependencies, at `projectRoot`:
- * what a build made from it now carries there, for `modulesOf`. Node only: an
- * Expo app calls it from `app.config.ts`, and passes it on in the config.
- *
- *     export default ({ config, projectRoot }: ConfigContext) => ({
- *       ...config,
- *       extra: {
- *         ...config.extra,
- *         backtick: { packages: installedPackages(projectRoot) },
- *       },
- *     });
+ * what a build made from it now carries there, for `modulesOf`. Node only:
+ * the app's build calls it, and embeds what it answers in the app.
+ * Packages are found as Metro finds them by default, in `node_modules` here
+ * or above: a `metro.config.js` that aliases or redirects them needs its own
+ * versions.
  */
 export function installedPackages(projectRoot: string): Record<string, string> {
   const { dependencies = {} } = JSON.parse(