Refactor builder API into a factory + separate types for interface (#1217)

* initial step of refactoring builder API to be created by a factory + the interface in builder/interface
* let's just go back to `any` here, this is wonky
* builder/interface.ts and builder/schema-to-ts.ts are now together entirely self contained!
* lots of types fixes for previous change
* more type fixes
* remove this syntax for now
* remove extraneous parameter for createBuilder
* add back ability to set schema with cell/opaqueRef
* fix more tests
* export opaqueRef directly still, for internal use outside of recipes
* partially fix test
* import type with `type` annotation
* interface is now truly just the public interface. users should only import one or the other
* separated imports in other places
* fix misaligned exports
* removed Mutable from interface
* change all recipes to import from /interface.
* redo use of SchemaWithoutCell in the right places, this fixed the tests
* need Mutable<> after all, so duplicating here to keep interface.ts and schema-tot-ts.ts together standalone
* recipe also needs SchemaWithoutCell
* and recipe needs that also for the recipe function!
* fix recipes
* move getRecipeEnvironment to public environment
* also exports constants via builder!

Author: seefeldb

AGENTS.md

@@ -33,6 +33,8 @@ The instructions in this document apply to the entire repository.
 - Prefer named exports over default exports.
 - Use package names for internal imports.
 - Destructure when importing multiple names from the same module.
+- Import either from `@commontools/builder` (internal API) or
+  `@commontools/builder/interface` (external API), but not both.
 
 ### Error Handling
 

packages/builder/deno.json

@@ -1,6 +1,9 @@
 {
   "name": "@commontools/builder",
-  "exports": "./src/index.ts",
+  "exports": { 
+    ".": "./src/index.ts", 
+    "./interface": "./src/interface.ts" 
+  },
   "tasks": {
     "test": "deno test --allow-env"
   }

packages/builder/src/built-in.ts

@@ -1,7 +1,12 @@
 import { createNodeFactory, lift } from "./module.ts";
-import { type Cell } from "@commontools/runner";
-import type { JSONSchema, NodeFactory, Opaque, OpaqueRef } from "./types.ts";
-import type { Schema } from "./schema-to-ts.ts";
+import type {
+  Cell,
+  JSONSchema,
+  NodeFactory,
+  Opaque,
+  OpaqueRef,
+  Schema,
+} from "./types.ts";
 
 export interface BuiltInLLMParams {
   messages?: string[];

packages/builder/src/factory.ts

@@ -0,0 +1,112 @@
+/**
+ * Factory function to create builder functions with runtime dependency injection
+ */
+
+import type {
+  BuilderFunctionsAndConstants,
+  Cell,
+  CreateCellFunction,
+  JSONSchema,
+} from "./types.ts";
+import { AuthSchema, ID, ID_FIELD, NAME, schema, TYPE, UI } from "./types.ts";
+import { opaqueRef, stream } from "./opaque-ref.ts";
+import { getTopFrame, recipe } from "./recipe.ts";
+import { byRef, compute, derive, handler, lift, render } from "./module.ts";
+import {
+  compileAndRun,
+  fetchData,
+  ifElse,
+  llm,
+  navigateTo,
+  str,
+  streamData,
+} from "./built-in.ts";
+import { getCellLinkOrThrow, type Runtime } from "@commontools/runner";
+import { getRecipeEnvironment } from "./env.ts";
+
+/**
+ * Creates a set of builder functions with the given runtime
+ * @param runtime - The runtime instance to use for cell creation
+ * @returns An object containing all builder functions
+ */
+export const createBuilder = (
+  runtime: Runtime,
+): BuilderFunctionsAndConstants => {
+  // Implementation of createCell moved from runner/harness
+  const createCell: CreateCellFunction = function createCell<T = any>(
+    schema?: JSONSchema,
+    name?: string,
+    value?: T,
+  ): Cell<T> {
+    const frame = getTopFrame();
+    // This is a rather hacky way to get the context, based on the
+    // unsafe_binding pattern. Once we replace that mechanism, let's add nicer
+    // abstractions for context here as well.
+    const cellLink = frame?.unsafe_binding?.materialize([]);
+    if (!frame || !frame.cause || !cellLink) {
+      throw new Error(
+        "Can't invoke createCell outside of a lifted function or handler",
+      );
+    }
+    if (!getCellLinkOrThrow) {
+      throw new Error(
+        "getCellLinkOrThrow function not provided to createBuilder",
+      );
+    }
+    const space = getCellLinkOrThrow(cellLink).cell.space;
+
+    const cause = { parent: frame.cause } as Record<string, any>;
+    if (name) cause.name = name;
+    else cause.number = frame.generatedIdCounter++;
+
+    // Cast to Cell<T> is necessary to cast to interface-only Cell type
+    const cell = runtime.getCell<T>(space, cause, schema) as Cell<T>;
+
+    if (value !== undefined) cell.set(value);
+
+    return cell;
+  } as CreateCellFunction;
+
+  return {
+    // Recipe creation
+    recipe,
+
+    // Module creation
+    lift,
+    handler,
+    derive,
+    compute,
+    render,
+
+    // Built-in modules
+    str,
+    ifElse,
+    llm,
+    fetchData,
+    streamData,
+    compileAndRun,
+    navigateTo,
+
+    // Cell creation
+    createCell,
+    cell: opaqueRef,
+    stream,
+
+    // Utility
+    byRef,
+
+    // Environment
+    getRecipeEnvironment,
+
+    // Constants
+    ID,
+    ID_FIELD,
+    TYPE,
+    NAME,
+    UI,
+
+    // Schema utilities
+    schema,
+    AuthSchema,
+  };
+};

packages/builder/src/index.ts

@@ -1,14 +1,11 @@
-export { opaqueRef as cell, stream } from "./opaque-ref.ts";
-export { $, event, select, Spell } from "./spell.ts";
-export {
-  byRef,
-  compute,
-  createNodeFactory,
-  derive,
-  handler,
-  lift,
-  render,
-} from "./module.ts";
+// Export the factory function
+export { createBuilder } from "./factory.ts";
+export type {
+  BuilderFunctionsAndConstants as BuilderFunctions,
+  BuilderRuntime,
+} from "./types.ts";
+
+// Internal functions and exports needed by other packages
 export {
   getRecipeEnvironment,
   type RecipeEnvironment,
@@ -19,26 +16,14 @@ export {
   popFrame,
   pushFrame,
   pushFrameFromCause,
-  recipe,
   recipeFromFrame,
 } from "./recipe.ts";
-export {
-  type BuiltInCompileAndRunParams,
-  type BuiltInCompileAndRunState,
-  type BuiltInLLMParams,
-  type BuiltInLLMState,
-  compileAndRun,
-  type createCell,
-  fetchData,
-  ifElse,
-  llm,
-  navigateTo,
-  str,
-  streamData,
-} from "./built-in.ts";
 export {
   type Alias,
+  AuthSchema,
+  type Cell,
   type Frame,
+  type HandlerFactory,
   ID,
   ID_FIELD,
   isAlias,
@@ -54,16 +39,17 @@ export {
   markAsStatic,
   type Module,
   type ModuleFactory,
-  type Mutable,
   NAME,
-  type Node,
   type NodeFactory,
   type Opaque,
   type OpaqueRef,
   type OpaqueRefMethods,
   type Recipe,
   type RecipeFactory,
-  type Static,
+  type Schema,
+  schema,
+  type SchemaWithoutCell,
+  type Stream,
   type StreamAlias,
   type toJSON,
   toOpaqueRef,
@@ -74,8 +60,9 @@ export {
   unsafe_parentRecipe,
   type UnsafeBinding,
 } from "./types.ts";
-export { type Schema, schema } from "./schema-to-ts.ts";
-export { AuthSchema } from "./schema-lib.ts";
+export { createNodeFactory } from "./module.ts";
+export { opaqueRef as cell } from "./opaque-ref.ts";
+export type { Mutable } from "@commontools/utils/types";
 
 // This should be a separate package, but for now it's easier to keep it here.
 export {