@backtickjs/react-native-client 0.1.8 → 0.1.9

package/README.md

@@ -12,20 +12,18 @@ npm install @backtickjs/react-native-client
 
 ## Usage
 
-Give `evaluate` the modules a bundle may require, then fetch a screen and draw it. Hold the request, a promise, in state in a component that doesn't suspend, so it outlives the render that waits for it, and draw it with React's `use` under `<Suspense>`:
+Give `evaluate` the module map: the modules a bundle may require, each loaded the first time one does. Then fetch a screen and draw it. Hold the request, a promise, in state in a component that doesn't suspend, so it outlives the render that waits for it, and draw it with React's `use` under `<Suspense>`:
 
 ```tsx
 import { evaluate } from "@backtickjs/react-native-client";
-import * as React from "react";
 import { Suspense, use, useState } from "react";
-import * as JSXRuntime from "react/jsx-runtime";
-import * as ReactNative from "react-native";
+import { ActivityIndicator } from "react-native";
 
 // What a screen may require: the packages this app was built with.
-const modules = {
-  react: React,
-  "react/jsx-runtime": JSXRuntime,
-  "react-native": ReactNative,
+const moduleMap = {
+  react: () => require("react"),
+  "react/jsx-runtime": () => require("react/jsx-runtime"),
+  "react-native": () => require("react-native"),
 };
 
 async function fetchScreen(url: string) {
@@ -33,7 +31,7 @@ async function fetchScreen(url: string) {
   if (!response.ok) {
     throw new Error(`${url} answered ${response.status}.`);
   }
-  return evaluate(await response.text(), modules) as React.ReactNode;
+  return evaluate(await response.text(), moduleMap) as React.ReactNode;
 }
 
 export default function App() {
@@ -41,7 +39,7 @@ export default function App() {
     fetchScreen("https://api.example.com/screens/home"),
   );
   return (
-    <Suspense fallback={<ReactNative.ActivityIndicator />}>
+    <Suspense fallback={<ActivityIndicator />}>
       <Screen screen={screen} />
     </Suspense>
   );
@@ -54,13 +52,13 @@ function Screen({ screen }: { screen: Promise<React.ReactNode> }) {
 
 Wrap the `<Suspense>` in an error boundary to show a screen that couldn't be fetched or run. To fetch again, set a new promise in state. The React Native template of [create-backtick-app](https://github.com/backtickjs/backtick/tree/main/packages/create-backtick-app) has the full version, with the boundary and a refetch whenever the development server restarts.
 
-The server bundles for the versions the app runs: it passes them to `bundler.build` as `packageVersions`, so they should match the packages you put in `modules`.
+The server bundles for the versions the app runs: it passes them to `bundler.build` as `modules`, so they should match the packages in your module map.
 
 ## API
 
-### `evaluate(code: string, modules: Modules): unknown`
+### `evaluate(code: string, moduleMap: ModuleMap): unknown`
 
-Runs `code` as a CommonJS module, with `require` answered from `modules`, and returns what it exports: for a Backtick screen, the element to draw. A bundle that requires a specifier missing from `modules` throws:
+Runs `code` as a CommonJS module, with `require` answered from `moduleMap`, and returns what it exports: for a Backtick screen, the element to draw. Each module loads the first time a bundle requires it, once for every bundle run with the same map. A bundle that requires a specifier missing from `moduleMap` throws:
 
 ```
 The bundle requires "expo-haptics", which this app doesn't provide.
@@ -68,13 +66,27 @@ The bundle requires "expo-haptics", which this app doesn't provide.
 
 Errors thrown while the bundle runs propagate to the caller.
 
-### `Modules`
+### `ModuleMap`
 
 ```ts
-type Modules = Readonly<Record<string, unknown>>;
+type ModuleMap = Readonly<Record<string, () => unknown>>;
 ```
 
-What a bundle may require, by specifier, each as its module namespace. At least `react`, `react/jsx-runtime` and `react-native`; add any other package the app chooses to offer its screens.
+What a bundle may require, by specifier, each as a function that returns its module. It does for an app what a web page's import map does, with modules for values instead of URLs. At least `react`, `react/jsx-runtime` and `react-native`; add any other package the app chooses to offer its screens. Keep the functions' `require` calls inside them: Metro still bundles each one, and Node tools can then read the specifiers without loading React Native.
+
+### `buildIdFrom(extra: unknown, platform: string): string`
+
+This build's id on `platform`, read from the app config's `extra.buildIds`, which an `app.config.ts` fills with [`@backtickjs/builds`](https://github.com/backtickjs/backtick/tree/main/packages/builds). The id names the modules the build carries, so the server bundles only screens it can run. Send it to the server however the app reaches it, as a header or a GraphQL variable:
+
+```ts
+import { buildIdFrom } from "@backtickjs/react-native-client";
+import Constants from "expo-constants";
+import { Platform } from "react-native";
+
+const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+```
+
+It throws when the config has no build id for the platform, as the app starts: no screen could be drawn for a build without one.
 
 ## Security
 
@@ -84,7 +96,7 @@ What a bundle may require, by specifier, each as its module namespace. At least
 
 - [`@backtickjs/core`](https://github.com/backtickjs/backtick/tree/main/packages/core): `cs` and the types for writing screens
 - [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler): builds the bundles this runs
-- [`@backtickjs/react-native`](https://github.com/backtickjs/backtick/tree/main/packages/react-native): React Native's components and APIs, to splice into scripts
+- [`@backtickjs/react-native`](https://github.com/backtickjs/backtick/tree/main/adapters/react-native): React Native's components and APIs, to splice into scripts
 - [`create-backtick-app`](https://github.com/backtickjs/backtick/tree/main/packages/create-backtick-app): an Expo app with a Backtick server beside it
 - [How it works](https://backtickjs.com/docs/how-it-works)
 - [Errors](https://backtickjs.com/docs/errors)

package/dist/index.d.ts

@@ -1,24 +1,36 @@
 /**
- * What a bundle may require, by specifier: the packages the app was built
- * with, each as its module. At least React, React Native and React's JSX
- * runtime:
+ * What a bundle may import, by specifier, and how this app loads each: a
+ * function returning the module, called the first time a bundle requires it.
+ * At least React, React Native and React's JSX runtime:
  *
- *     import * as React from "react";
- *     import * as JSXRuntime from "react/jsx-runtime";
- *     import * as ReactNative from "react-native";
- *
- *     const modules = {
- *       "react": React,
- *       "react/jsx-runtime": JSXRuntime,
- *       "react-native": ReactNative,
+ *     const moduleMap = {
+ *       react: () => require("react"),
+ *       "react/jsx-runtime": () => require("react/jsx-runtime"),
+ *       "react-native": () => require("react-native"),
  *     };
+ *
+ * What a web page's import map does, for an app: the values are modules,
+ * not URLs.
+ * Loaded lazily, so a module no screen uses never loads, and Node can read
+ * the specifiers without loading React Native.
  */
-export type Modules = Readonly<Record<string, unknown>>;
+export type ModuleMap = Readonly<Record<string, () => unknown>>;
 /**
- * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * A bundle's code, run as CommonJS with `require` answered from `moduleMap`:
  * what it exports, the screen to draw. What a web page's import map and
  * script tag do for a browser, this does for an app; fetching the bundle, and
  * when, is the app's. A bundle requiring a module the app doesn't provide
  * throws.
  */
-export declare function evaluate(code: string, modules: Modules): unknown;
+export declare function evaluate(code: string, moduleMap: ModuleMap): unknown;
+/**
+ * This build's id on `platform`, from the app config's `extra`, where an
+ * `app.config.ts` puts `buildIds` from `@backtickjs/builds`: it names the
+ * modules the build carries, for the server to bundle screens it can run.
+ * Send it however the app reaches its server: a header, a GraphQL variable.
+ * Throws for an app config without it, as the app starts: no screen could be
+ * drawn for a build without an id.
+ *
+ *     const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+ */
+export declare function buildIdFrom(extra: unknown, platform: string): string;

package/dist/index.js

@@ -1,19 +1,48 @@
+// Each map's modules, once loaded: one instance of each, as `require` gives.
+const loaded = new WeakMap();
 /**
- * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * A bundle's code, run as CommonJS with `require` answered from `moduleMap`:
  * what it exports, the screen to draw. What a web page's import map and
  * script tag do for a browser, this does for an app; fetching the bundle, and
  * when, is the app's. A bundle requiring a module the app doesn't provide
  * throws.
  */
-export function evaluate(code, modules) {
-    const module = { exports: {} };
+export function evaluate(code, moduleMap) {
+    let modules = loaded.get(moduleMap);
+    if (modules === undefined) {
+        modules = new Map();
+        loaded.set(moduleMap, modules);
+    }
     const require = (specifier) => {
-        if (!Object.hasOwn(modules, specifier)) {
+        if (!Object.hasOwn(moduleMap, specifier)) {
             throw new Error(`The bundle requires "${specifier}", which this app doesn't provide.`);
         }
-        return modules[specifier];
+        if (!modules.has(specifier)) {
+            modules.set(specifier, moduleMap[specifier]());
+        }
+        return modules.get(specifier);
     };
+    const module = { exports: {} };
     new Function("module", "exports", "require", code)(module, module.exports, require);
     return module.exports;
 }
+/**
+ * This build's id on `platform`, from the app config's `extra`, where an
+ * `app.config.ts` puts `buildIds` from `@backtickjs/builds`: it names the
+ * modules the build carries, for the server to bundle screens it can run.
+ * Send it however the app reaches its server: a header, a GraphQL variable.
+ * Throws for an app config without it, as the app starts: no screen could be
+ * drawn for a build without an id.
+ *
+ *     const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+ */
+export function buildIdFrom(extra, platform) {
+    const ids = extra
+        ?.buildIds;
+    const id = ids?.[platform];
+    if (typeof id !== "string") {
+        throw new Error(`No build id for ${platform} in the app config: is app.config.ts adding buildIds from @backtickjs/builds?`);
+    }
+    return id;
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAgB;IACrD,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,EAAa,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAW,EAAE;QAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,oCAAoC,CACtE,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC,CAAC;IACF,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAChD,MAAM,EACN,MAAM,CAAC,OAAO,EACd,OAAO,CACR,CAAC;IACF,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,6EAA6E;AAC7E,MAAM,MAAM,GAAG,IAAI,OAAO,EAAmC,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,SAAoB;IACzD,IAAI,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;QACpB,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAW,EAAE;QAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,oCAAoC,CACtE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,SAAS,CAAE,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,EAAa,EAAE,CAAC;IAC1C,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAChD,MAAM,EACN,MAAM,CAAC,OAAO,EACd,OAAO,CACR,CAAC;IACF,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,QAAgB;IAC1D,MAAM,GAAG,GAAI,KAA4D;QACvE,EAAE,QAAQ,CAAC;IACb,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC3B,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,+EAA+E,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtickjs/react-native-client",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Runs a Backtick server's screens in a React Native app, with the app's own packages",
   "keywords": [
     "backtick",

package/src/index.ts

@@ -1,37 +1,49 @@
 /**
- * What a bundle may require, by specifier: the packages the app was built
- * with, each as its module. At least React, React Native and React's JSX
- * runtime:
+ * What a bundle may import, by specifier, and how this app loads each: a
+ * function returning the module, called the first time a bundle requires it.
+ * At least React, React Native and React's JSX runtime:
  *
- *     import * as React from "react";
- *     import * as JSXRuntime from "react/jsx-runtime";
- *     import * as ReactNative from "react-native";
- *
- *     const modules = {
- *       "react": React,
- *       "react/jsx-runtime": JSXRuntime,
- *       "react-native": ReactNative,
+ *     const moduleMap = {
+ *       react: () => require("react"),
+ *       "react/jsx-runtime": () => require("react/jsx-runtime"),
+ *       "react-native": () => require("react-native"),
  *     };
+ *
+ * What a web page's import map does, for an app: the values are modules,
+ * not URLs.
+ * Loaded lazily, so a module no screen uses never loads, and Node can read
+ * the specifiers without loading React Native.
  */
-export type Modules = Readonly<Record<string, unknown>>;
+export type ModuleMap = Readonly<Record<string, () => unknown>>;
+
+// Each map's modules, once loaded: one instance of each, as `require` gives.
+const loaded = new WeakMap<ModuleMap, Map<string, unknown>>();
 
 /**
- * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * A bundle's code, run as CommonJS with `require` answered from `moduleMap`:
  * what it exports, the screen to draw. What a web page's import map and
  * script tag do for a browser, this does for an app; fetching the bundle, and
  * when, is the app's. A bundle requiring a module the app doesn't provide
  * throws.
  */
-export function evaluate(code: string, modules: Modules): unknown {
-  const module = { exports: {} as unknown };
+export function evaluate(code: string, moduleMap: ModuleMap): unknown {
+  let modules = loaded.get(moduleMap);
+  if (modules === undefined) {
+    modules = new Map();
+    loaded.set(moduleMap, modules);
+  }
   const require = (specifier: string): unknown => {
-    if (!Object.hasOwn(modules, specifier)) {
+    if (!Object.hasOwn(moduleMap, specifier)) {
       throw new Error(
         `The bundle requires "${specifier}", which this app doesn't provide.`,
       );
     }
-    return modules[specifier];
+    if (!modules.has(specifier)) {
+      modules.set(specifier, moduleMap[specifier]!());
+    }
+    return modules.get(specifier);
   };
+  const module = { exports: {} as unknown };
   new Function("module", "exports", "require", code)(
     module,
     module.exports,
@@ -39,3 +51,25 @@ export function evaluate(code: string, modules: Modules): unknown {
   );
   return module.exports;
 }
+
+/**
+ * This build's id on `platform`, from the app config's `extra`, where an
+ * `app.config.ts` puts `buildIds` from `@backtickjs/builds`: it names the
+ * modules the build carries, for the server to bundle screens it can run.
+ * Send it however the app reaches its server: a header, a GraphQL variable.
+ * Throws for an app config without it, as the app starts: no screen could be
+ * drawn for a build without an id.
+ *
+ *     const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+ */
+export function buildIdFrom(extra: unknown, platform: string): string {
+  const ids = (extra as { buildIds?: Record<string, unknown> } | undefined)
+    ?.buildIds;
+  const id = ids?.[platform];
+  if (typeof id !== "string") {
+    throw new Error(
+      `No build id for ${platform} in the app config: is app.config.ts adding buildIds from @backtickjs/builds?`,
+    );
+  }
+  return id;
+}