@backtickjs/core 0.1.11 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 The `cs` tag and the types around it. A client script, written `` cs`…` `` inside a server component, is code that runs on the client; values from the server cross into it as splices written `$name`, type-checked on both sides. Every Backtick app imports `cs` from here, whatever its UI framework.
 
-`cs` is compiled at build time, so a project also needs a build plugin (`@backtickjs/node-plugin` or `@backtickjs/bun-plugin`), an adapter for its framework (`@backtickjs/react`, `@backtickjs/react-native` or `@backtickjs/solid-js`) and `@backtickjs/tsc` for type checking. Called without the compiler, `cs` throws. `npx create-backtick-app@latest` sets all of this up.
+`cs` is compiled at build time, so a project also needs a build plugin (`@backtickjs/node-plugin` or `@backtickjs/bun-plugin`), its framework's JSX package (`@backtickjs/jsx-react` or `@backtickjs/jsx-solid`) and `@backtickjs/tsc` for type checking. Called without the compiler, `cs` throws. `npx create-backtick-app@latest` sets all of this up.
 
 ## Install
 
@@ -16,7 +16,7 @@ A server component reads data on the server and returns a client script. A clien
 
 ```tsx
 import { cs } from "@backtickjs/core";
-import { useState } from "@backtickjs/react";
+import { useState } from "react" with { backtick: "client" };
 
 // A client component: it runs on the client.
 const Counter = cs`(props: { start: number }) => {
@@ -42,27 +42,21 @@ A script every component shares, like a context or a store, is made once with `o
 
 ```tsx
 import { cs, once } from "@backtickjs/core";
-import { createContext, useContext } from "@backtickjs/react";
+import { createContext, useContext } from "react" with { backtick: "client" };
 
 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:
+To use a package the client provides, import it with `with { backtick: "client" }`. The server never loads it: each name is what the client provides, typed as the package types it, and a script splices it:
 
 ```ts
-import { createImport } from "@backtickjs/core";
-
-const greet = createImport<() => string>({
-  name: "greet",
-  from: "my-native-module",
-  version: "^1.0.0",
-});
+import { greet } from "my-native-module" with { backtick: "client" };
 // In a script: cs`<p>{$greet()}</p>`
 ```
 
-The client must provide that package, and the server must list it in the bundler's `modules` at a version in that range.
+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.
 
 ## API
 
@@ -79,13 +73,13 @@ The client must provide that package, and the server must list it in the bundler
 - `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 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.
+- `createJsxElement`, `isJsxElement`, `JsxElement`, `JsxElementOf`, `JsxElementTypeOf`: what a server-side JSX tag evaluates to before bundling. 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
 
 - [`@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/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/jsx-react`](https://github.com/backtickjs/backtick/tree/main/packages/jsx-react), [`@backtickjs/jsx-solid`](https://github.com/backtickjs/backtick/tree/main/packages/jsx-solid): each framework's JSX
 - [`@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/ClientImport.d.ts

@@ -1,7 +1,8 @@
 import type { Client } from "./Client.js";
 /**
  * An export of a module the client provides, held as a value: what a script
- * splices to use it, and what a bundle imports it by.
+ * splices to use it, and what a bundle imports it by. The compiler writes one
+ * per name of `import { View } from "react-native" with { backtick: "client" }`.
  */
 export interface ClientImport<T> extends Client<T> {
     readonly "@backtickjs": "ClientImport";

package/dist/ClientImport.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientImport.js","sourceRoot":"","sources":["../src/ClientImport.ts"],"names":[],"mappings":"AAeA,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,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAI,EAC9B,IAAI,EACJ,IAAI,EACJ,OAAO,GAKR;IACC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,IAAI;QACJ,IAAI;QACJ,OAAO;KACsB,CAAC;AAClC,CAAC"}
+{"version":3,"file":"ClientImport.js","sourceRoot":"","sources":["../src/ClientImport.ts"],"names":[],"mappings":"AAiBA,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,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAI,EAC9B,IAAI,EACJ,IAAI,EACJ,OAAO,GAKR;IACC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,IAAI;QACJ,IAAI;QACJ,OAAO;KACsB,CAAC;AAClC,CAAC"}

package/dist/ClientModule.d.ts

@@ -0,0 +1,8 @@
+import type { Client } from "./Client.js";
+/**
+ * A module's exports as client imports, each typed by its declaration: what
+ * the editor checks the names of a client import against.
+ */
+export type ClientModule<M> = {
+    readonly [Name in keyof M]: Client<M[Name]>;
+};

package/dist/ClientModule.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ClientModule.js.map

package/dist/ClientModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientModule.js","sourceRoot":"","sources":["../src/ClientModule.ts"],"names":[],"mappings":""}

package/dist/ClientScript.d.ts

@@ -6,7 +6,7 @@ export type Param = {
     kind: "capture";
     key: string;
 };
-export interface ClientModule {
+export interface ScriptModule {
     readonly id: string;
     readonly code: string;
     readonly map: string;
@@ -16,9 +16,9 @@ export interface ClientModule {
 }
 export interface ClientScript {
     readonly "@backtickjs": "ClientScript";
-    readonly module: ClientModule;
+    readonly module: ScriptModule;
     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;
+export declare function create(module: ScriptModule, args: readonly Spliceable[]): ClientScript;

package/dist/JsxElement.d.ts

@@ -2,8 +2,8 @@ import type { Client } from "./Client.js";
 /**
  * What a JSX tag evaluates to on the server, before bundling resolves it: the
  * tag and its props, which are the server's own. What a drawing is, is the
- * adapter's; this is what the bundler expands. A client value, of the type its
- * adapter names (Solid's: its element), so a host may hand one over wherever
+ * JSX package's; this is what the bundler expands. A client value, of the type
+ * its JSX package names (Solid's: its element), so a host may hand one over wherever
  * a drawing may stand.
  */
 export interface JsxElement extends Client<unknown> {

package/dist/index.d.ts

@@ -7,7 +7,8 @@ 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 { create, type ClientModule, type ClientScript, isClientScript, type Param, } from "./ClientScript.js";
+export { create, type ScriptModule, type ClientScript, isClientScript, type Param, } from "./ClientScript.js";

package/dist/index.js

@@ -8,7 +8,7 @@ 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 an adapter's JSX runtime makes, and
+// A drawing as a host builds one: what a JSX package's runtime makes, and
 // what the bundler expands.
 export { createJsxElement, isJsxElement, } from "./JsxElement.js";
 // What a template compiles to: the compiler writes one and the bundler reads

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;AAK3B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAmB,MAAM,WAAW,CAAC;AAEhE,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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtickjs/core",
-  "version": "0.1.11",
+  "version": "0.2.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/ClientImport.ts

@@ -2,14 +2,16 @@ import type { Client } from "./Client.js";
 
 /**
  * An export of a module the client provides, held as a value: what a script
- * splices to use it, and what a bundle imports it by.
+ * splices to use it, and what a bundle imports it by. The compiler writes one
+ * per name of `import { View } from "react-native" with { backtick: "client" }`.
  */
 export interface ClientImport<T> extends Client<T> {
   readonly "@backtickjs": "ClientImport";
+  // the export, or `*` for the module's namespace
   readonly name: string;
   // the specifier the client resolves
   readonly from: string;
-  // the versions of `from`'s package it works with, a semver range
+  // the exact version of `from`'s package it's typed against
   readonly version: string;
 }
 

package/src/ClientModule.ts

@@ -0,0 +1,7 @@
+import type { Client } from "./Client.js";
+
+/**
+ * A module's exports as client imports, each typed by its declaration: what
+ * the editor checks the names of a client import against.
+ */
+export type ClientModule<M> = { readonly [Name in keyof M]: Client<M[Name]> };

package/src/ClientScript.ts

@@ -10,7 +10,7 @@ export type Param =
   | { kind: "capture"; key: string };
 
 // The compiled code of one `cs`, shared by every script it creates.
-export interface ClientModule {
+export interface ScriptModule {
   // `<fileHash>:<line>:<column>` of the `cs`. The hash keeps ids from two
   // files apart: they match only when the files are identical.
   readonly id: string;
@@ -35,7 +35,7 @@ export interface ClientModule {
 // flag reads the same.
 export interface ClientScript {
   readonly "@backtickjs": "ClientScript";
-  readonly module: ClientModule;
+  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
@@ -53,7 +53,7 @@ export function isClientScript(value: unknown): value is ClientScript {
 }
 
 export function create(
-  module: ClientModule,
+  module: ScriptModule,
   args: readonly Spliceable[],
 ): ClientScript {
   return { "@backtickjs": "ClientScript", module, args };

package/src/JsxElement.ts

@@ -3,8 +3,8 @@ import type { Client } from "./Client.js";
 /**
  * What a JSX tag evaluates to on the server, before bundling resolves it: the
  * tag and its props, which are the server's own. What a drawing is, is the
- * adapter's; this is what the bundler expands. A client value, of the type its
- * adapter names (Solid's: its element), so a host may hand one over wherever
+ * JSX package's; this is what the bundler expands. A client value, of the type
+ * its JSX package names (Solid's: its element), so a host may hand one over wherever
  * a drawing may stand.
  */
 export interface JsxElement extends Client<unknown> {
@@ -29,7 +29,7 @@ export function createJsxElement(
   return { "@backtickjs": "JsxElement", type, props } as JsxElement;
 }
 
-// What an adapter's JSX namespace types its `Element` and `ElementType` as,
+// What a JSX package's namespace types its `Element` and `ElementType` as,
 // given what its framework draws (Solid's `JSX.Element`, React's `ReactNode`).
 // One namespace types both a host's JSX and a script's, so each type answers
 // for both sides.

package/src/index.ts

@@ -17,13 +17,14 @@ export {
   isClientImport,
   type ClientImport,
 } from "./ClientImport.js";
+export type { ClientModule } from "./ClientModule.js";
 // A bundle's code, typed by what it runs to, and, in a script, executing
 // another as this one was. The one an app starts from is executed by
 // `@backtickjs/core/cjs` or `@backtickjs/core/es`.
 export type { Bundle } from "./Bundle.js";
 export { exec, isClientExec, type ClientExec } from "./exec.js";
 
-// A drawing as a host builds one: what an adapter's JSX runtime makes, and
+// A drawing as a host builds one: what a JSX package's runtime makes, and
 // what the bundler expands.
 export {
   createJsxElement,
@@ -37,7 +38,7 @@ export {
 // it, so the shape is neither end's.
 export {
   create,
-  type ClientModule,
+  type ScriptModule,
   type ClientScript,
   isClientScript,
   type Param,