@backtickjs/core 0.3.2 → 0.4.0

package/README.md

@@ -38,13 +38,13 @@ 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.dev/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.
+A script is one value for the bundle, made when it loads, as a module-level `const` is: a context or a store every component shares is written as one. Code that runs at each use is a function, called where it's used.
 
 ```tsx
-import { cs, once } from "@backtickjs/core";
+import { cs } from "@backtickjs/core";
 import { createContext, useContext } from "react" with { backtick: "client" };
 
-const ThemeContext = once(cs`$createContext("light")`);
+const ThemeContext = cs`$createContext("light")`;
 const Label = cs`() => <p>{$useContext($ThemeContext)}</p>`;
 // In a script: <$ThemeContext.Provider value="dark"><$Label /></$ThemeContext.Provider>
 ```
@@ -112,7 +112,6 @@ A test draws a screen with a module map of its own, stand-ins included; its modu
 
 - `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.
@@ -125,7 +124,7 @@ A test draws a screen with a module map of its own, stand-ins included; its modu
 - `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.
-- `createJsxElement`, `isJsxElement`, `JsxElement`, `JsxElementOf`, `JsxElementTypeOf`: what a server-side JSX tag evaluates to before bundling. Used by the JSX packages' runtimes.
+- `createJsxElement`, `isJsxElement`, `JsxElement`, `JsxElementOf`, `ServerComponent`: what a server-side JSX tag evaluates to before bundling, and what a server component answers. Used by the JSX packages' runtimes.
 - `create`, `isClientScript`, `ClientScript`, `ScriptModule`, `Param`: the compiled form of a script, written by the compiler and read by the bundler. Not for application code.
 
 ## Related

package/dist/ClientScript.d.ts

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

package/dist/ClientScript.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientScript.js","sourceRoot":"","sources":["../src/ClientScript.ts"],"names":[],"mappings":"AA6CA,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":"AA0CA,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/JsxElement.d.ts

@@ -20,9 +20,7 @@ export declare function createJsxElement(type: string | ((props: never) => unkno
  */
 export type JsxElementOf<T> = T & Client<T>;
 /**
- * What a tag may name: an intrinsic element; a component as a script sees it,
- * answering what the framework draws (a client component, or a server
- * component lowered); or a server component on the host, answering a script
- * that draws, or nothing.
+ * A server component on the host: it answers a script that draws a `T`, or
+ * nothing, which the bundler expands where its element stands.
  */
-export type JsxElementTypeOf<T> = string | ((props: never) => T) | ((props: never) => Client<T> | null | Promise<Client<T> | null>);
+export type ServerComponent<T> = (props: never) => Client<T> | null | Promise<Client<T> | null>;

package/dist/cs.d.ts

@@ -1,7 +1,8 @@
 import type { Client } from "./Client.js";
 import { create } from "./ClientScript.js";
 import type { Spliceable, SplicesAs, Spliced } from "./Spliceable.js";
-declare function lift<T>(_: T): Client<T>;
+type NoValue = "a script that makes no value: a script is one value, made at load. To run code where it's used, make it a function, cs`() => …`, and call it";
+declare function lift<T extends (<U>() => U extends T ? 1 : 2) extends <U>() => U extends void ? 1 : 2 ? NoValue : unknown>(_: T): Client<T>;
 declare function splice<T extends [T] extends [SplicesAs<T>] ? unknown : Spliceable>(_: T): unknown extends Spliced<T> ? any : Spliced<T>;
 declare function awaited<T>(_: T): Awaited<T>;
 /**

package/dist/cs.js.map

@@ -1 +1 @@
-{"version":3,"file":"cs.js","sourceRoot":"","sources":["../src/cs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,uBAAuB;AACvB,SAAS,IAAI,CAAI,CAAI;IACnB,MAAM,IAAI,KAAK,CACb,+DAA+D;QAC7D,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,0EAA0E;AAC1E,yEAAyE;AACzE,gFAAgF;AAChF,sEAAsE;AACtE,uEAAuE;AACvE,SAAS,MAAM,CACb,CAAI;IAEJ,MAAM,IAAI,KAAK,CACb,iEAAiE;QAC/D,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,gDAAgD;AAChD,SAAS,OAAO,CAAI,CAAI;IACtB,MAAM,IAAI,KAAK,CACb,kEAAkE;QAChE,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAC7B,CAAC,QAA8B,EAAE,GAAG,OAAkB,EAAmB,EAAE;IACzE,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAC;AACJ,CAAC,EACD,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAClC,CAAC"}
+{"version":3,"file":"cs.js","sourceRoot":"","sources":["../src/cs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAQ3C,uBAAuB;AACvB,SAAS,IAAI,CAQX,CAAI;IACJ,MAAM,IAAI,KAAK,CACb,+DAA+D;QAC7D,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,0EAA0E;AAC1E,yEAAyE;AACzE,gFAAgF;AAChF,sEAAsE;AACtE,uEAAuE;AACvE,SAAS,MAAM,CACb,CAAI;IAEJ,MAAM,IAAI,KAAK,CACb,iEAAiE;QAC/D,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,gDAAgD;AAChD,SAAS,OAAO,CAAI,CAAI;IACtB,MAAM,IAAI,KAAK,CACb,kEAAkE;QAChE,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAC7B,CAAC,QAA8B,EAAE,GAAG,OAAkB,EAAmB,EAAE;IACzE,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAC;AACJ,CAAC,EACD,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAClC,CAAC"}

package/dist/index.d.ts

@@ -4,12 +4,11 @@
  */
 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 type { ClientModule } from "./ClientModule.js";
 export type { Bundle } from "./Bundle.js";
 export { exec, isClientExec, type ClientExec } from "./exec.js";
-export { createJsxElement, isJsxElement, type JsxElement, type JsxElementOf, type JsxElementTypeOf, } from "./JsxElement.js";
+export { createJsxElement, isJsxElement, type JsxElement, type JsxElementOf, type ServerComponent, } from "./JsxElement.js";
 export { create, type ScriptModule, type ClientScript, isClientScript, type Param, } from "./ClientScript.js";
 export { modulesOf, type ModuleMap } from "./modulesOf.js";

package/dist/index.js

@@ -5,7 +5,6 @@
 // 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";
 export { exec, isClientExec } from "./exec.js";
 // A drawing as a host builds one: what a JSX package's runtime makes, and

package/dist/index.js.map

@@ -1 +1 @@
-{"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;AAM3B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAmB,MAAM,WAAW,CAAC;AAEhE,0EAA0E;AAC1E,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;AAE3B,2EAA2E;AAC3E,gDAAgD;AAChD,OAAO,EAAE,SAAS,EAAkB,MAAM,gBAAgB,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;AAM7B,OAAO,EACL,YAAY,EACZ,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAmB,MAAM,WAAW,CAAC;AAEhE,0EAA0E;AAC1E,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;AAE3B,2EAA2E;AAC3E,gDAAgD;AAChD,OAAO,EAAE,SAAS,EAAkB,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtickjs/core",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "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

@@ -38,9 +38,6 @@ export interface ClientScript {
   readonly module: ScriptModule;
   // 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/JsxElement.ts

@@ -42,12 +42,9 @@ export function createJsxElement(
 export type JsxElementOf<T> = T & Client<T>;
 
 /**
- * What a tag may name: an intrinsic element; a component as a script sees it,
- * answering what the framework draws (a client component, or a server
- * component lowered); or a server component on the host, answering a script
- * that draws, or nothing.
+ * A server component on the host: it answers a script that draws a `T`, or
+ * nothing, which the bundler expands where its element stands.
  */
-export type JsxElementTypeOf<T> =
-  | string
-  | ((props: never) => T)
-  | ((props: never) => Client<T> | null | Promise<Client<T> | null>);
+export type ServerComponent<T> = (
+  props: never,
+) => Client<T> | null | Promise<Client<T> | null>;

package/src/cs.ts

@@ -2,8 +2,21 @@ import type { Client } from "./Client.js";
 import { create } from "./ClientScript.js";
 import type { Spliceable, SplicesAs, Spliced } from "./Spliceable.js";
 
+// A string, so the error says it: `void` has no properties for TypeScript to
+// name as missing.
+type NoValue =
+  "a script that makes no value: a script is one value, made at load. To run code where it's used, make it a function, cs`() => …`, and call it";
+
 // The root of a script
-function lift<T>(_: T): Client<T> {
+function lift<
+  // Whether `T` is exactly `void`: two such functions are the same type only
+  // when `T` and `void` are, so `never`, `any` and `undefined` pass.
+  T extends (<U>() => U extends T ? 1 : 2) extends <U>() => U extends void
+    ? 1
+    : 2
+    ? NoValue
+    : unknown,
+>(_: T): Client<T> {
   throw new Error(
     "Don't call `cs.lift` directly; it's used to generate virtual " +
       "code for the typechecker. Write code using cs`...` instead.",

package/src/index.ts

@@ -7,7 +7,6 @@
 // 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.
@@ -31,7 +30,7 @@ export {
   isJsxElement,
   type JsxElement,
   type JsxElementOf,
-  type JsxElementTypeOf,
+  type ServerComponent,
 } from "./JsxElement.js";
 
 // What a template compiles to: the compiler writes one and the bundler reads

package/dist/once.d.ts

@@ -1,11 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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/src/once.ts

@@ -1,40 +0,0 @@
-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+$/, "");
-}