@backtickjs/core 0.1.4 → 0.1.5

package/README.md

@@ -36,9 +36,7 @@ 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. A server component is drawn inside a script through a splice: `{${<Footer />}}`.
-
-What can be spliced is `Spliceable`: strings, numbers, booleans, `null`, `undefined`, plain arrays and objects of those, and scripts. Host functions and class instances can't be spliced; a function the client calls is written as a script, `` cs`(n: number) => …` ``.
+`$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.
 
 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:
 
@@ -63,6 +61,7 @@ The client must provide that package, and the server must list it in the bundler
 - `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.
 - `isClientImport`, `ClientImport`: 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 adapters' JSX runtimes.
 - `create`, `isClientScript`, `ClientScript`, `ClientModule`, `Param`: the compiled form of a script, written by the compiler and read by the bundler. Not for application code.
 
@@ -72,7 +71,7 @@ The client must provide that package, and the server must list it in the bundler
 - [`@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/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
-- [Documentation](https://backtickjs.com/docs)
+- [Thinking in Backtick](https://backtickjs.com/docs/thinking-in-backtick), [Scripts in depth](https://backtickjs.com/docs/scripts-in-depth)
 
 ## License
 

package/dist/Client.d.ts

@@ -1,4 +1,10 @@
 declare const ClientBrand: unique symbol;
+/**
+ * A client script, as the host holds it: a value the client computes as a
+ * `T`. The host can't read the `T`, which doesn't exist until the client runs
+ * the script; it can splice the script into another, pass it around, and
+ * return it from a server component.
+ */
 export interface Client<T> {
     readonly [ClientBrand]: T;
 }

package/dist/Spliceable.d.ts

@@ -2,14 +2,22 @@ import type { Client } from "./Client.js";
 /**
  * What the host may splice: the value written out, a script standing in for
  * it, or a container mixing the two. Not a host function, which is host code:
- * a client function is a script, cs`(n: number) => …`. An index signature rather than a mapped
- * type, so it can be named in a `satisfies` without a type to walk.
+ * a client function is a script, cs`(n: number) => …`. Matches an object
+ * through an index signature, which TypeScript gives a type alias but never an
+ * interface: a splice checks with `SplicesAs`, which takes either.
  */
-export type Spliceable = Client<unknown> | null | undefined | number | boolean | string | readonly Spliceable[] | {
+export type Spliceable = Client<unknown> | null | undefined | number | bigint | boolean | string | readonly Spliceable[] | {
     readonly [key: string]: Spliceable;
 };
-export type Spliced<T> = T extends Client<infer U> ? U : T extends readonly (infer Item extends Spliceable)[] ? Spliced<Item>[] : T extends {
-    readonly [key: string]: Spliceable;
-} ? {
+/**
+ * `T` as a splice checks it, member by member, so it takes an interface as a
+ * type alias. What already is
+ * `Spliceable` is as it is; a function, which can't cross, is checked against
+ * `Spliceable`, and fails.
+ */
+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 ? {
     -readonly [K in keyof T]: Spliced<T[K]>;
 } : T;

package/dist/cs.d.ts

@@ -1,9 +1,8 @@
 import type { Client } from "./Client.js";
 import { create } from "./ClientScript.js";
-import type { Spliceable } from "./Spliceable.js";
-import type { Spliced } from "./Spliceable.js";
+import type { Spliceable, SplicesAs, Spliced } from "./Spliceable.js";
 declare function lift<T>(_: T): Client<T>;
-declare function splice<T extends [T] extends [Spliceable] ? unknown : Spliceable>(_: T): unknown extends Spliced<T> ? any : Spliced<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>;
 /**
  * The globals a project declares — its libs, `@types`, a `declare global` —
@@ -14,6 +13,17 @@ declare function awaited<T>(_: T): Awaited<T>;
 export type GlobalThis = {
     [Key in keyof typeof globalThis]: (typeof globalThis)[Key];
 };
+/**
+ * Writes a client script: code in the host's files that runs on the client.
+ * The template is one expression, one block in braces, or one function; a
+ * function that returns JSX is a client component. `$name` and
+ * `${expression}` splice host values into it. Returns a `Client<T>`, `T`
+ * being what the script computes. Compiled when the host loads the file, by
+ * a Backtick plugin; called uncompiled, it throws.
+ *
+ * `cs.globalThis` is what a name the script didn't bind is read off. In the
+ * type and not in the object: nothing runs the virtual code it is written in.
+ */
 export declare const cs: ((_strings: TemplateStringsArray, ..._values: unknown[]) => Client<unknown>) & {
     awaited: typeof awaited;
     create: typeof create;

package/dist/cs.js

@@ -6,9 +6,10 @@ function lift(_) {
 }
 // A constraint that is `unknown` for a value that splices, rather than
 // `Spliceable` itself or an intersection with it: either of those keeps a
-// literal a literal instead of widening it. What can't be spliced is refused
-// once, where it is written, and is `any` after: refused, `T` falls back to
-// `Spliceable`, which splices to `unknown`.
+// literal a literal instead of widening it. Checked member by member, as
+// `SplicesAs<T>`, so an interface splices too. What can't be spliced is refused
+// once, where it is written, as not `Spliceable`, and is `any` after:
+// refused, `T` falls back to `Spliceable`, which splices to `unknown`.
 function splice(_) {
     throw new Error("Don't call `cs.splice` directly; it's used to generate virtual " +
         "code for the typechecker. Write code using cs`...` instead.");
@@ -26,8 +27,17 @@ const members = {
     lift,
     splice,
 };
-// `globalThis`, which a name the script didn't bind is read off. In the type
-// and not in the object: nothing runs the virtual code it is written in.
+/**
+ * Writes a client script: code in the host's files that runs on the client.
+ * The template is one expression, one block in braces, or one function; a
+ * function that returns JSX is a client component. `$name` and
+ * `${expression}` splice host values into it. Returns a `Client<T>`, `T`
+ * being what the script computes. Compiled when the host loads the file, by
+ * a Backtick plugin; called uncompiled, it throws.
+ *
+ * `cs.globalThis` is what a name the script didn't bind is read off. In the
+ * type and not in the object: nothing runs the virtual code it is written in.
+ */
 export const cs = Object.assign((_strings, ..._values) => {
     throw new Error("`cs` was not compiled. Is @backtickjs set up for this project?");
 }, members);

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;AAI3C,uBAAuB;AACvB,SAAS,IAAI,CAAI,CAAI;IACnB,MAAM,IAAI,KAAK,CACb,+DAA+D;QAC7D,6DAA6D,CAChE,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,0EAA0E;AAC1E,6EAA6E;AAC7E,4EAA4E;AAC5E,4CAA4C;AAC5C,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,0BAA0B;AAC1B,MAAM,OAAO,GAAG;IACd,OAAO;IACP,MAAM;IACN,IAAI;IACJ,MAAM;CACP,CAAC;AAYF,6EAA6E;AAC7E,yEAAyE;AACzE,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,OAEC,CACF,CAAC"}
+{"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,0BAA0B;AAC1B,MAAM,OAAO,GAAG;IACd,OAAO;IACP,MAAM;IACN,IAAI;IACJ,MAAM;CACP,CAAC;AAYF;;;;;;;;;;GAUG;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,OAEC,CACF,CAAC"}

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  */
 export { cs } from "./cs.js";
 export type { Client } from "./Client.js";
-export type { Spliceable, Spliced } from "./Spliceable.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";
 export { create, type ClientModule, type ClientScript, isClientScript, type Param, } from "./ClientScript.js";

package/package.json

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

package/src/Client.ts

@@ -1,4 +1,11 @@
 declare const ClientBrand: unique symbol;
+
+/**
+ * A client script, as the host holds it: a value the client computes as a
+ * `T`. The host can't read the `T`, which doesn't exist until the client runs
+ * the script; it can splice the script into another, pass it around, and
+ * return it from a server component.
+ */
 export interface Client<T> {
   readonly [ClientBrand]: T;
 }

package/src/Spliceable.ts

@@ -3,19 +3,33 @@ import type { Client } from "./Client.js";
 /**
  * What the host may splice: the value written out, a script standing in for
  * it, or a container mixing the two. Not a host function, which is host code:
- * a client function is a script, cs`(n: number) => …`. An index signature rather than a mapped
- * type, so it can be named in a `satisfies` without a type to walk.
+ * a client function is a script, cs`(n: number) => …`. Matches an object
+ * through an index signature, which TypeScript gives a type alias but never an
+ * interface: a splice checks with `SplicesAs`, which takes either.
  */
 export type Spliceable =
   | Client<unknown>
   | null
   | undefined
   | number
+  | bigint
   | boolean
   | string
   | readonly Spliceable[]
   | { readonly [key: string]: Spliceable };
 
+/**
+ * `T` as a splice checks it, member by member, so it takes an interface as a
+ * type alias. What already is
+ * `Spliceable` is as it is; a function, which can't cross, is checked against
+ * `Spliceable`, and fails.
+ */
+export type SplicesAs<T> = [T] extends [Spliceable]
+  ? T
+  : T extends (...args: never) => unknown
+    ? Spliceable
+    : { readonly [K in keyof T]: SplicesAs<T[K]> };
+
 // What a spliceable becomes on the client:
 //   Client<U>                 -> U
 //   T[]                       -> Spliced<T>[]
@@ -26,6 +40,6 @@ export type Spliced<T> =
     ? U
     : T extends readonly (infer Item extends Spliceable)[]
       ? Spliced<Item>[]
-      : T extends { readonly [key: string]: Spliceable }
+      : T extends object
         ? { -readonly [K in keyof T]: Spliced<T[K]> }
         : T;

package/src/cs.ts

@@ -1,7 +1,6 @@
 import type { Client } from "./Client.js";
 import { create } from "./ClientScript.js";
-import type { Spliceable } from "./Spliceable.js";
-import type { Spliced } from "./Spliceable.js";
+import type { Spliceable, SplicesAs, Spliced } from "./Spliceable.js";
 
 // The root of a script
 function lift<T>(_: T): Client<T> {
@@ -13,10 +12,11 @@ function lift<T>(_: T): Client<T> {
 
 // A constraint that is `unknown` for a value that splices, rather than
 // `Spliceable` itself or an intersection with it: either of those keeps a
-// literal a literal instead of widening it. What can't be spliced is refused
-// once, where it is written, and is `any` after: refused, `T` falls back to
-// `Spliceable`, which splices to `unknown`.
-function splice<T extends [T] extends [Spliceable] ? unknown : Spliceable>(
+// literal a literal instead of widening it. Checked member by member, as
+// `SplicesAs<T>`, so an interface splices too. What can't be spliced is refused
+// once, where it is written, as not `Spliceable`, and is `any` after:
+// refused, `T` falls back to `Spliceable`, which splices to `unknown`.
+function splice<T extends [T] extends [SplicesAs<T>] ? unknown : Spliceable>(
   _: T,
 ): unknown extends Spliced<T> ? any : Spliced<T> {
   throw new Error(
@@ -52,8 +52,17 @@ export type GlobalThis = {
   [Key in keyof typeof globalThis]: (typeof globalThis)[Key];
 };
 
-// `globalThis`, which a name the script didn't bind is read off. In the type
-// and not in the object: nothing runs the virtual code it is written in.
+/**
+ * Writes a client script: code in the host's files that runs on the client.
+ * The template is one expression, one block in braces, or one function; a
+ * function that returns JSX is a client component. `$name` and
+ * `${expression}` splice host values into it. Returns a `Client<T>`, `T`
+ * being what the script computes. Compiled when the host loads the file, by
+ * a Backtick plugin; called uncompiled, it throws.
+ *
+ * `cs.globalThis` is what a name the script didn't bind is read off. In the
+ * type and not in the object: nothing runs the virtual code it is written in.
+ */
 export const cs = Object.assign(
   (_strings: TemplateStringsArray, ..._values: unknown[]): Client<unknown> => {
     throw new Error(

package/src/index.ts

@@ -9,7 +9,7 @@ export type { Client } from "./Client.js";
 
 // What a host may hand a client: data, a script, or an export of a module the
 // client provides.
-export type { Spliceable, Spliced } from "./Spliceable.js";
+export type { Spliceable, SplicesAs, Spliced } from "./Spliceable.js";
 export {
   createImport,
   isClientImport,