experimental-ash 0.18.2 → 0.19.0

package/dist/src/shared/sandbox-definition.d.ts

@@ -25,13 +25,28 @@ export interface SandboxDefinition<BO = Record<string, never>, SO = Record<strin
     /**
      * Backend that runs this sandbox.
      *
+     * Accepts either a {@link SandboxBackend} value or a zero-arg factory
+     * function that returns one. The factory form is invoked lazily on
+     * first framework access and the result is memoized for the lifetime
+     * of the process, so backend-internal state (such as the Vercel
+     * backend's prewarmed-template cache) is preserved across every call.
+     * Use the factory form to defer evaluation — for example, when create
+     * options depend on environment variables that aren't set at module
+     * load time:
+     *
+     * ```ts
+     * defineSandbox({
+     *   backend: () => vercelBackend({ env: { TOKEN: process.env.TOKEN ?? "" } }),
+     * });
+     * ```
+     *
      * When this field is omitted, Ash substitutes `defaultBackend()` at
      * runtime, which delegates to `vercelBackend()` on hosted Vercel
      * (where `process.env.VERCEL` is set) and to `localBackend()`
      * everywhere else. Set `backend` explicitly to pin the sandbox to a
      * specific backend regardless of environment.
      */
-    backend: SandboxBackend<BO, SO>;
+    backend: SandboxBackend<BO, SO> | (() => SandboxBackend<BO, SO>);
     bootstrap?(input: SandboxBootstrapContext<BO>): Promise<void> | void;
     onSession?(input: SandboxSessionContext<SO>): Promise<void> | void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"