@backtickjs/core 0.1.8 → 0.1.9

package/README.md

@@ -38,6 +38,17 @@ export async function Home() {
 
 `$node` and `$Counter` are splices: `node` is a server variable, written into the bundle as data; `Counter` is a script. `$useState` is a splice too, of an export the client provides. What can be spliced is `Spliceable`: data, and scripts. [Thinking in Backtick](https://backtickjs.com/docs/thinking-in-backtick) has what can cross, what can't, and how server and client components compose.
 
+A script every component shares, like a context or a store, is made once with `once`: one value for the bundle, where an expression script would run again at each read.
+
+```tsx
+import { cs, once } from "@backtickjs/core";
+import { createContext, useContext } from "@backtickjs/react";
+
+const ThemeContext = once(cs`$createContext("light")`);
+const Label = cs`() => <p>{$useContext($ThemeContext)}</p>`;
+// In a script: <$ThemeContext.Provider value="dark"><$Label /></$ThemeContext.Provider>
+```
+
 To use a package the client provides beyond what an adapter covers, describe its export with `createImport`. `from` is the specifier the bundle imports, and `version` the semver range of its package that the export works with:
 
 ```ts
@@ -51,12 +62,13 @@ const greet = createImport<() => string>({
 // In a script: cs`<p>{$greet()}</p>`
 ```
 
-The client must provide that package, and the server must list it in the bundler's `packageVersions` at a version in that range.
+The client must provide that package, and the server must list it in the bundler's `modules` at a version in that range.
 
 ## API
 
 - `cs`: the tag for client scripts. Compiled at build time; throws if called uncompiled.
 - `Client<T>`: the type of a script that stands for a `T` on the client.
+- `once(script)`: the script as one value for the bundle, made at its top; each call is one value. Refused for a script that reads a variable of the script around it.
 - `Spliceable`: what a server may splice into a script.
 - `Spliced<T>`: what a spliceable value becomes on the client (`Client<U>` becomes `U`; arrays and objects map member by member).
 - `createImport<T>({ name, from, version })`: an export of a module the client provides, as a value a script can splice.
@@ -68,7 +80,7 @@ The client must provide that package, and the server must list it in the bundler
 ## Related
 
 - [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler): runs server components and writes the bundle
-- [`@backtickjs/react`](https://github.com/backtickjs/backtick/tree/main/packages/react), [`@backtickjs/react-native`](https://github.com/backtickjs/backtick/tree/main/packages/react-native), [`@backtickjs/solid-js`](https://github.com/backtickjs/backtick/tree/main/packages/solid-js): framework adapters
+- [`@backtickjs/react`](https://github.com/backtickjs/backtick/tree/main/adapters/react), [`@backtickjs/react-native`](https://github.com/backtickjs/backtick/tree/main/adapters/react-native), [`@backtickjs/solid-js`](https://github.com/backtickjs/backtick/tree/main/adapters/solid-js): framework adapters
 - [`@backtickjs/node-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/node-plugin), [`@backtickjs/bun-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/bun-plugin): compile scripts as your server loads them
 - [`@backtickjs/tsc`](https://github.com/backtickjs/backtick/tree/main/packages/tsc): type-checks scripts and their splices
 - [Thinking in Backtick](https://backtickjs.com/docs/thinking-in-backtick), [Scripts in depth](https://backtickjs.com/docs/scripts-in-depth)

package/dist/ClientScript.d.ts

@@ -18,6 +18,7 @@ export interface ClientScript {
     readonly "@backtickjs": "ClientScript";
     readonly module: ClientModule;
     readonly args: readonly Spliceable[];
+    readonly once?: true;
 }
 export declare function isClientScript(value: unknown): value is ClientScript;
 export declare function create(module: ClientModule, args: readonly Spliceable[]): ClientScript;

package/dist/ClientScript.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientScript.js","sourceRoot":"","sources":["../src/ClientScript.ts"],"names":[],"mappings":"AAsCA,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,aAAa,IAAI,KAAK;QACtB,KAAK,CAAC,aAAa,CAAC,KAAK,cAAc,CACxC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,MAAM,CACpB,MAAoB,EACpB,IAA2B;IAE3B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACzD,CAAC"}
+{"version":3,"file":"ClientScript.js","sourceRoot":"","sources":["../src/ClientScript.ts"],"names":[],"mappings":"AA4CA,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,aAAa,IAAI,KAAK;QACtB,KAAK,CAAC,aAAa,CAAC,KAAK,cAAc,CACxC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,MAAM,CACpB,MAAoB,EACpB,IAA2B;IAE3B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACzD,CAAC"}

package/dist/Spliceable.d.ts

@@ -18,6 +18,8 @@ export type Spliceable = Client<unknown> | null | undefined | number | bigint |
 export type SplicesAs<T> = [T] extends [Spliceable] ? T : T extends (...args: never) => unknown ? Spliceable : {
     readonly [K in keyof T]: SplicesAs<T[K]>;
 };
-export type Spliced<T> = T extends Client<infer U> ? U : T extends readonly (infer Item extends Spliceable)[] ? Spliced<Item>[] : T extends object ? {
+export type Spliced<T> = T extends Client<infer U> ? U : T extends readonly (infer Item extends Spliceable)[] ? number extends T["length"] ? Spliced<Item>[] : {
+    -readonly [K in keyof T]: Spliced<T[K]>;
+} : T extends object ? {
     -readonly [K in keyof T]: Spliced<T[K]>;
 } : T;

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  */
 export { cs } from "./cs.js";
 export type { Client } from "./Client.js";
+export { once } from "./once.js";
 export type { Spliceable, SplicesAs, Spliced } from "./Spliceable.js";
 export { createImport, isClientImport, type ClientImport, } from "./ClientImport.js";
 export { createJsxElement, isJsxElement, type JsxElement, type JsxElementOf, type JsxElementTypeOf, } from "./JsxElement.js";

package/dist/index.js

@@ -2,8 +2,10 @@
  * Backtick: the `cs` tag, what a host may hand a client, and what a template
  * compiles to.
  */
-// The tag, and how a host language spells a script standing in for a value.
+// The tag, and how a host language spells a script standing in for a value;
+// a script as one value for the bundle.
 export { cs } from "./cs.js";
+export { once } from "./once.js";
 export { createImport, isClientImport, } from "./ClientImport.js";
 // A drawing as a host builds one: what an adapter's JSX runtime makes, and
 // what the bundler expands.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAM7B,OAAO,EACL,YAAY,EACZ,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAE3B,2EAA2E;AAC3E,4BAA4B;AAC5B,OAAO,EACL,gBAAgB,EAChB,YAAY,GAIb,MAAM,iBAAiB,CAAC;AAEzB,6EAA6E;AAC7E,qCAAqC;AACrC,OAAO,EACL,MAAM,EAGN,cAAc,GAEf,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,wCAAwC;AACxC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKjC,OAAO,EACL,YAAY,EACZ,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAE3B,2EAA2E;AAC3E,4BAA4B;AAC5B,OAAO,EACL,gBAAgB,EAChB,YAAY,GAIb,MAAM,iBAAiB,CAAC;AAEzB,6EAA6E;AAC7E,qCAAqC;AACrC,OAAO,EACL,MAAM,EAGN,cAAc,GAEf,MAAM,mBAAmB,CAAC"}

package/dist/once.d.ts

@@ -0,0 +1,11 @@
+import type { Client } from "./Client.js";
+/**
+ * A script as one value for the bundle: its code runs once, at the top of the
+ * bundle, and every read is that value, as a module-level `const` is in plain
+ * TypeScript. For what every component shares, a context or a store, which an
+ * expression would make again at each read. Each call of `once` is one value.
+ *
+ * Refused for a script that reads a variable of the script around it: at the
+ * top of the bundle, nothing encloses it.
+ */
+export declare function once<T>(script: Client<T>): Client<T>;

package/dist/once.js

@@ -0,0 +1,31 @@
+import { isClientScript, } from "./ClientScript.js";
+/**
+ * A script as one value for the bundle: its code runs once, at the top of the
+ * bundle, and every read is that value, as a module-level `const` is in plain
+ * TypeScript. For what every component shares, a context or a store, which an
+ * expression would make again at each read. Each call of `once` is one value.
+ *
+ * Refused for a script that reads a variable of the script around it: at the
+ * top of the bundle, nothing encloses it.
+ */
+export function once(script) {
+    if (!isClientScript(script)) {
+        throw new Error("`once` takes a script, cs`…`.");
+    }
+    const capture = script.module.params.find(isCapture);
+    if (capture !== undefined) {
+        throw new Error(`Can't make this script \`once\`: it reads \`${sourceName(capture.key)}\` ` +
+            "from the script around it, and a `once` value is made at the top " +
+            "of the bundle, outside every script.");
+    }
+    const made = { ...script, once: true };
+    return made;
+}
+function isCapture(param) {
+    return param.kind === "capture";
+}
+// A binding key is `<name>$<fileHash>$<n>`.
+function sourceName(key) {
+    return key.replace(/\$[0-9a-z]+\$\d+$/, "");
+}
+//# sourceMappingURL=once.js.map

package/dist/once.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"once.js","sourceRoot":"","sources":["../src/once.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAAI,MAAiB;IACvC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACrD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,+CAA+C,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK;YACzE,mEAAmE;YACnE,sCAAsC,CACzC,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAiB,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACrD,OAAO,IAA4B,CAAC;AACtC,CAAC;AAED,SAAS,SAAS,CAAC,KAAY;IAC7B,OAAO,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;AAClC,CAAC;AAED,4CAA4C;AAC5C,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC"}

package/package.json

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

package/src/ClientScript.ts

@@ -28,12 +28,18 @@ export interface ClientModule {
   readonly kind: "function" | "expression" | "block";
 }
 
-// One run of a `cs`: its module, and the values that run passes it.
+// One run of a `cs`: its module, and the values that run passes it. The rest
+// are flags, how the bundle treats the script: each optional, absent meaning
+// the plain script, so code that makes or spreads a script without knowing a
+// flag reads the same.
 export interface ClientScript {
   readonly "@backtickjs": "ClientScript";
   readonly module: ClientModule;
   // one per splice, in parameter order
   readonly args: readonly Spliceable[];
+  // one value for the bundle, made at its top, rather than code run at each
+  // read: see `once`
+  readonly once?: true;
 }
 
 export function isClientScript(value: unknown): value is ClientScript {

package/src/Spliceable.ts

@@ -32,14 +32,18 @@ export type SplicesAs<T> = [T] extends [Spliceable]
 
 // What a spliceable becomes on the client:
 //   Client<U>                 -> U
-//   T[]                       -> Spliced<T>[]
+//   T[], [A, B]               -> Spliced<T>[], [Spliced<A>, Spliced<B>]
 //   { k: T }                  -> { k: Spliced<T> }
 //   primitives                -> unchanged
+// A tuple maps homomorphically, which keeps it a tuple; any other array stays
+// `Spliced<Item>[]`, which TypeScript defers, so `Spliceable[]` doesn't recurse.
 export type Spliced<T> =
   T extends Client<infer U>
     ? U
     : T extends readonly (infer Item extends Spliceable)[]
-      ? Spliced<Item>[]
+      ? number extends T["length"]
+        ? Spliced<Item>[]
+        : { -readonly [K in keyof T]: Spliced<T[K]> }
       : T extends object
         ? { -readonly [K in keyof T]: Spliced<T[K]> }
         : T;

package/src/index.ts

@@ -3,9 +3,11 @@
  * compiles to.
  */
 
-// The tag, and how a host language spells a script standing in for a value.
+// The tag, and how a host language spells a script standing in for a value;
+// a script as one value for the bundle.
 export { cs } from "./cs.js";
 export type { Client } from "./Client.js";
+export { once } from "./once.js";
 
 // What a host may hand a client: data, a script, or an export of a module the
 // client provides.

package/src/once.ts

@@ -0,0 +1,40 @@
+import type { Client } from "./Client.js";
+import {
+  type ClientScript,
+  isClientScript,
+  type Param,
+} from "./ClientScript.js";
+
+/**
+ * A script as one value for the bundle: its code runs once, at the top of the
+ * bundle, and every read is that value, as a module-level `const` is in plain
+ * TypeScript. For what every component shares, a context or a store, which an
+ * expression would make again at each read. Each call of `once` is one value.
+ *
+ * Refused for a script that reads a variable of the script around it: at the
+ * top of the bundle, nothing encloses it.
+ */
+export function once<T>(script: Client<T>): Client<T> {
+  if (!isClientScript(script)) {
+    throw new Error("`once` takes a script, cs`…`.");
+  }
+  const capture = script.module.params.find(isCapture);
+  if (capture !== undefined) {
+    throw new Error(
+      `Can't make this script \`once\`: it reads \`${sourceName(capture.key)}\` ` +
+        "from the script around it, and a `once` value is made at the top " +
+        "of the bundle, outside every script.",
+    );
+  }
+  const made: ClientScript = { ...script, once: true };
+  return made as unknown as Client<T>;
+}
+
+function isCapture(param: Param): param is Extract<Param, { kind: "capture" }> {
+  return param.kind === "capture";
+}
+
+// A binding key is `<name>$<fileHash>$<n>`.
+function sourceName(key: string): string {
+  return key.replace(/\$[0-9a-z]+\$\d+$/, "");
+}