@breadboard-ai/build - npm Package Compare versions

Comparing version 0.7.1 to 0.8.0

CHANGELOG.md

 # Changelog
 
+## 0.8.0
+
+### Minor Changes
+
+- 2312443: Add support for `deprecated` and `experimental` tags on Kits.
+
+### Patch Changes
+
+- ad8aa22: Add kit function to build for making kits
+- f78ec0a: Add intersect function to breadboard type expressions system for intersecting two objects
+- b76f9a1: Add id, metadata, and breadboardType to component definition classes
+- 15ae381: Fix optional output serialization
+- Updated dependencies [1e1be2a]
+- Updated dependencies [2b094a3]
+- Updated dependencies [fa93c3f]
+- Updated dependencies [215bd15]
+- Updated dependencies [2b9ef5b]
+- Updated dependencies [a0852df]
+- Updated dependencies [2312443]
+- Updated dependencies [6ffa89c]
+  - @google-labs/breadboard@0.23.0
+
 ## 0.7.1
@@ -4,0 +26,0 @@

dist/index.d.ts

@@ -6,7 +6,2 @@ /**
  */
-import { type Convergence } from "./internal/board/converge.js";
-import { type Input, type InputWithDefault } from "./internal/board/input.js";
-import { type Loopback } from "./internal/board/loopback.js";
-import { type OutputPortReference } from "./internal/common/port.js";
-import type { BreadboardType, JsonSerializable } from "./internal/type-system/type.js";
 export { board } from "./internal/board/board.js";
@@ -17,10 +12,13 @@ export { constant } from "./internal/board/constant.js";
 export { loopback } from "./internal/board/loopback.js";
+export { optionalEdge } from "./internal/board/optional.js";
 export { output } from "./internal/board/output.js";
 export { serialize } from "./internal/board/serialize.js";
 export { unsafeCast } from "./internal/board/unsafe-cast.js";
-export type { SerializableBoard, } from "./internal/common/serializable.js";
+export { type SerializableBoard, } from "./internal/common/serializable.js";
+export { extractTypeFromValue, type Value } from "./internal/common/value.js";
 export { defineNodeType } from "./internal/define/define.js";
-export type { NodeFactoryFromDefinition } from "./internal/define/node-factory.js";
-export { optionalEdge } from "./internal/board/optional.js";
+export { jsonSchemaToPortConfigMap as fromJSONSchema } from "./internal/define/json-schema.js";
+export { type NodeFactoryFromDefinition } from "./internal/define/node-factory.js";
 export { unsafeSchema } from "./internal/define/unsafe-schema.js";
+export { kit } from "./internal/kit.js";
 export { annotate } from "./internal/type-system/annotate.js";
@@ -30,21 +28,5 @@ export { anyOf } from "./internal/type-system/any-of.js";
 export { enumeration } from "./internal/type-system/enumeration.js";
+export { intersect } from "./internal/type-system/intersect.js";
 export { object, optional } from "./internal/type-system/object.js";
 export { toJSONSchema } from "./internal/type-system/type.js";
-export { jsonSchemaToPortConfigMap as fromJSONSchema } from "./internal/define/json-schema.js";
 export { unsafeType } from "./internal/type-system/unsafe.js";
-/**
- * A value, or something that can stand-in for a value when wiring together
- * boards.
- *
- * For example, for a string, this could be any of:
- *
- * - An actual string.
- * - A string-typed output port.
- * - A node with a primary string-typed output port.
- * - A string-typed `input`.
- */
-export type Value<T extends JsonSerializable> = T | OutputPortReference<T> | Input<T> | InputWithDefault<T> | Loopback<T> | Convergence<T>;
-/**
- * Given a Breadboard {@link Value}, determine its JSON Schema type.
- */
-export declare function extractTypeFromValue(value: Value<JsonSerializable>): BreadboardType;

dist/index.js

@@ -6,7 +6,2 @@ /**
  */
-import { isConvergence } from "./internal/board/converge.js";
-import { isSpecialInput, } from "./internal/board/input.js";
-import { isLoopback } from "./internal/board/loopback.js";
-import { isOutputPortReference, OutputPortGetter, } from "./internal/common/port.js";
-import { anyOf } from "./internal/type-system/any-of.js";
 export { board } from "./internal/board/board.js";
@@ -17,8 +12,13 @@ export { constant } from "./internal/board/constant.js";
 export { loopback } from "./internal/board/loopback.js";
+export { optionalEdge } from "./internal/board/optional.js";
 export { output } from "./internal/board/output.js";
 export { serialize } from "./internal/board/serialize.js";
 export { unsafeCast } from "./internal/board/unsafe-cast.js";
+export {} from "./internal/common/serializable.js";
+export { extractTypeFromValue } from "./internal/common/value.js";
 export { defineNodeType } from "./internal/define/define.js";
-export { optionalEdge } from "./internal/board/optional.js";
+export { jsonSchemaToPortConfigMap as fromJSONSchema } from "./internal/define/json-schema.js";
+export {} from "./internal/define/node-factory.js";
 export { unsafeSchema } from "./internal/define/unsafe-schema.js";
+export { kit } from "./internal/kit.js";
 export { annotate } from "./internal/type-system/annotate.js";
@@ -28,36 +28,6 @@ export { anyOf } from "./internal/type-system/any-of.js";
 export { enumeration } from "./internal/type-system/enumeration.js";
+export { intersect } from "./internal/type-system/intersect.js";
 export { object, optional } from "./internal/type-system/object.js";
 export { toJSONSchema } from "./internal/type-system/type.js";
-export { jsonSchemaToPortConfigMap as fromJSONSchema } from "./internal/define/json-schema.js";
 export { unsafeType } from "./internal/type-system/unsafe.js";
-/**
- * Given a Breadboard {@link Value}, determine its JSON Schema type.
- */
-export function extractTypeFromValue(value) {
-    if (typeof value === "string") {
-        return "string";
-    }
-    if (typeof value === "number") {
-        return "number";
-    }
-    if (typeof value === "boolean") {
-        return "boolean";
-    }
-    if (value === null) {
-        return "null";
-    }
-    if (isOutputPortReference(value)) {
-        return value[OutputPortGetter].type;
-    }
-    if (isSpecialInput(value)) {
-        return value.type;
-    }
-    if (isLoopback(value)) {
-        return value.type;
-    }
-    if (isConvergence(value)) {
-        return anyOf(...value.ports.map((port) => extractTypeFromValue(port)));
-    }
-    return "unknown";
-}
 //# sourceMappingURL=index.js.map

dist/internal/board/board.d.ts

@@ -9,4 +9,5 @@ /**
 import type { JSONSchema4 } from "json-schema";
+import type { Value } from "../../index.js";
 import { InputPort, OutputPort, type OutputPortReference, type ValuesOrOutputPorts } from "../common/port.js";
-import type { SerializableInputPort, SerializableOutputPortReference } from "../common/serializable.js";
+import type { SerializableInputPort, SerializableOutputPort, SerializableOutputPortReference } from "../common/serializable.js";
 import { type JsonSerializable } from "../type-system/type.js";
@@ -37,3 +38,3 @@ import { type GenericSpecialInput, type Input, type InputWithDefault } from "./input.js";
  */
-export declare function board<IPORTS extends BoardInputShape, OPORTS extends BoardOutputShape>({ inputs, outputs, title, description, version, metadata, }: BoardParameters<IPORTS, OPORTS>): BoardDefinition<FlattenMultiInputs<IPORTS>, FlattenMultiOutputs<OPORTS>>;
+export declare function board<IPORTS extends BoardInputShape, OPORTS extends BoardOutputShape>({ inputs, outputs, id, title, description, version, metadata, }: BoardParameters<IPORTS, OPORTS>): BoardDefinition<FlattenMultiInputs<IPORTS>, FlattenMultiOutputs<OPORTS>>;
 export type FlattenMultiInputs<I extends BoardInputShape> = I extends Array<BoardInputPortsWithUndefined> ? {
@@ -48,2 +49,3 @@ [K in keyof I[number] as K extends "$id" | "$metadata" ? never : K]-?: I[number][K] extends Input<infer T> | undefined ? undefined extends I[number][K] ? Input<T | undefined> : Input<T> : never;
     outputs: OPORTS;
+    id?: string;
     title?: string;
@@ -81,2 +83,3 @@ description?: string;
 export type BoardDefinition<IPORTS extends BoardInputPorts, OPORTS extends BoardOutputPorts> = BoardInstantiateFunction<IPORTS, OPORTS> & {
+    readonly id?: string;
     readonly inputs: IPORTS;
@@ -94,10 +97,18 @@ readonly inputsForSerialization: BoardInputPorts | Array<BoardInputPorts>;
 type BoardInstantiateFunction<IPORTS extends BoardInputPorts, OPORTS extends BoardOutputPorts> = (values: ValuesOrOutputPorts<ExtractPortTypes<IPORTS>>) => BoardInstance<IPORTS, OPORTS>;
-declare class BoardInstance<IPORTS extends BoardInputPorts, OPORTS extends BoardOutputPorts> {
+export declare class BoardInstance<IPORTS extends BoardInputPorts, OPORTS extends BoardOutputPorts> {
     #private;
     readonly inputs: IPORTS;
     readonly outputs: OPORTS;
-    constructor(inputs: IPORTS, outputs: OPORTS, values: ValuesOrOutputPorts<ExtractPortTypes<IPORTS>>);
+    readonly values: ValuesOrOutputPorts<ExtractPortTypes<IPORTS>>;
+    readonly definition: BoardDefinition<IPORTS, OPORTS>;
+    constructor(inputs: IPORTS, outputs: OPORTS, values: ValuesOrOutputPorts<ExtractPortTypes<IPORTS>>, definition: BoardDefinition<IPORTS, OPORTS>);
 }
+export declare function isBoardInstance(value: unknown): value is BoardInstance<BoardInputPorts, BoardOutputPorts>;
+export type BoardOutput = (OutputPortReference<JsonSerializable> | Output<JsonSerializable> | Input<JsonSerializable> | InputWithDefault<JsonSerializable>) & {
+    innerBoard: BoardInstance<BoardInputPorts, BoardOutputPorts>;
+    innerPortName: string;
+};
+export declare function isBoardOutput(value: unknown): value is BoardOutput;
 type ExtractPortTypes<PORTS extends BoardInputPorts | BoardOutputPorts> = {
-    [PORT_NAME in keyof PORTS]: PORTS[PORT_NAME] extends InputPort<infer TYPE> | OutputPortReference<infer TYPE> ? TYPE : never;
+    [PORT_NAME in keyof PORTS]: PORTS[PORT_NAME] extends InputPort<infer TYPE> | Value<infer TYPE> ? TYPE : never;
 };
@@ -114,2 +125,3 @@ export declare function isBoard(value: unknown): value is GenericBoardDefinition;
 export declare function isSerializableOutputPortReference(value: unknown): value is SerializableOutputPortReference;
+export declare function unroll(value: Input<JsonSerializable> | InputWithDefault<JsonSerializable> | Output<JsonSerializable> | OutputPort<JsonSerializable> | OutputPortReference<JsonSerializable> | SerializableOutputPort): Input<JsonSerializable> | InputWithDefault<JsonSerializable> | OutputPort<JsonSerializable> | SerializableOutputPort;
 export {};

dist/internal/board/board.js

@@ -35,7 +35,8 @@ /**
  */
-export function board({ inputs, outputs, title, description, version, metadata, }) {
+export function board({ inputs, outputs, id, title, description, version, metadata, }) {
     const flatInputs = flattenInputs(inputs);
     const flatOutputs = flattenOutputs(outputs);
-    const def = new BoardDefinitionImpl(flatInputs, flatOutputs);
-    return Object.assign(def.instantiate.bind(def), {
+    const defImpl = new BoardDefinitionImpl(flatInputs, flatOutputs);
+    const definition = Object.assign(defImpl.instantiate.bind(defImpl), {
+        id,
         inputs: flatInputs,
@@ -50,4 +51,9 @@ inputsForSerialization: inputs,
         isBoard: true,
-        describe: def.describe.bind(def),
+        describe: defImpl.describe.bind(defImpl),
     });
+    // TODO(aomarks) This is a bit silly, need a small refactor here so that we
+    // aren't juggling all these objects. The complexity here comes from the fact
+    // that we want to return a function that also has data attached.
+    defImpl.definition = definition;
+    return definition;
 }
@@ -86,2 +92,3 @@ function flattenInputs(inputs) {
     #outputs;
+    definition;
     constructor(inputs, outputs) {
@@ -92,3 +99,3 @@ this.#inputs = inputs;
     instantiate(values) {
-        return new BoardInstance(this.#inputs, this.#outputs, values);
+        return new BoardInstance(this.#inputs, this.#outputs, values, this.definition);
     }
@@ -126,22 +133,38 @@ async describe() {
 }
-function getSchema(value) {
-    if ("type" in value) {
-        return toJSONSchema(value.type);
-    }
-    if (OutputPortGetter in value) {
-        return getSchema(value[OutputPortGetter]);
-    }
-    return getSchema(value.port);
-}
-class BoardInstance {
+export class BoardInstance {
     inputs;
     outputs;
-    // TODO(aomarks) This should get used somewhere.
-    #values;
-    constructor(inputs, outputs, values) {
+    values;
+    definition;
+    constructor(inputs, outputs, values, definition) {
         this.inputs = inputs;
-        this.outputs = outputs;
-        this.#values = values;
+        this.outputs = this.#tagOutputs(outputs);
+        this.values = values;
+        this.definition = definition;
     }
+    /**
+     * Tag all of our outputs with a link back this board instance. This allows us
+     * to recognize when we are hitting a board boundary during serialization,
+     * which is important because we need to do special stuff there (e.g. create
+     * an invoke node).
+     */
+    #tagOutputs(outputs) {
+        return Object.fromEntries(Object.entries(outputs).map(([name, output]) => [
+            name,
+            {
+                ...output,
+                innerPortName: name,
+                innerBoard: this,
+            },
+        ]));
+    }
 }
+export function isBoardInstance(value) {
+    // TODO(aomarks) Use a better brand
+    return (value
+        .definition !== undefined);
+}
+export function isBoardOutput(value) {
+    return value.innerBoard !== undefined;
+}
 export function isBoard(value) {
@@ -190,2 +213,3 @@ return (typeof value === "function" && "isBoard" in value && value.isBoard === true);
     }
+    const required = !isOptional(port);
     if (isSerializableOutputPortReference(port)) {
@@ -195,3 +219,3 @@ port = port[OutputPortGetter];
     // Input<JsonSerializable> | InputWithDefault<JsonSerializable> | SerializableOutputPort | OutputPort<...>
-    const schema = toJSONSchema(port.type);
+    const schema = toJSONSchema(unroll(port).type);
     if (isSpecialOutput(output)) {
@@ -205,3 +229,2 @@ if (output.title !== undefined) {
     }
-    const required = !isOptional(port);
     return { schema, required };
@@ -212,2 +235,14 @@ }
 }
+export function unroll(value) {
+    if (isSpecialOutput(value)) {
+        return unroll(value.port);
+    }
+    if ("type" in value) {
+        return value;
+    }
+    if (isOutputPortReference(value)) {
+        return unroll(value[OutputPortGetter]);
+    }
+    return value;
+}
 //# sourceMappingURL=board.js.map

dist/internal/board/output.d.ts

@@ -9,3 +9,3 @@ /**
 import type { Input, InputWithDefault } from "./input.js";
-export declare function output<T extends JsonSerializable>(port: OutputPortReference<T> | Input<T> | InputWithDefault<T>, { id, title, description, }?: {
+export declare function output<T extends JsonSerializable>(port: Output<T> | OutputPortReference<T> | Input<T> | InputWithDefault<T>, { id, title, description, }?: {
     id?: string;
@@ -20,4 +20,4 @@ title?: string;
     readonly description?: string;
-    readonly port: OutputPortReference<T> | Input<T> | InputWithDefault<T>;
+    readonly port: Output<T> | OutputPortReference<T> | Input<T> | InputWithDefault<T>;
 }
 export declare function isSpecialOutput(value: unknown): value is Output<JsonSerializable>;

dist/internal/board/serialize.js

@@ -8,3 +8,3 @@ /**
 import {} from "../type-system/type.js";
-import { describeInput, describeOutput, isBoard, isSerializableOutputPortReference, } from "./board.js";
+import { BoardInstance, describeInput, describeOutput, isBoard, isBoardInstance, isBoardOutput, isSerializableOutputPortReference, } from "./board.js";
 import { ConstantVersionOf, isConstant } from "./constant.js";
@@ -138,2 +138,3 @@ import { isConvergence } from "./converge.js";
             }
+            let nested = isBoardOutput(output) ? output : undefined;
             let port;
@@ -144,9 +145,11 @@ let outputNodeId;
                 port = output.port;
-                outputNodeId = output.id;
-                if (output.title) {
-                    portMetadata.title = output.title;
+                if (nested === undefined) {
+                    outputNodeId = output.id;
+                    if (output.title) {
+                        portMetadata.title = output.title;
+                    }
+                    if (output.description) {
+                        portMetadata.description = output.description;
+                    }
                 }
-                if (output.description) {
-                    portMetadata.description = output.description;
-                }
             }
@@ -156,2 +159,3 @@ else {
             }
+            nested = nested ?? (isBoardOutput(port) ? port : undefined);
             if (isSerializableOutputPortReference(port)) {
@@ -188,3 +192,7 @@ port = port[OutputPortGetter];
             }
-            if (isSpecialInput(port)) {
+            if (nested !== undefined) {
+                const { innerBoard, innerPortName } = nested;
+                addEdge(visitNodeAndReturnItsId(innerBoard), innerPortName, outputNodeId, name, isConstant(output), !required);
+            }
+            else if (isSpecialInput(port)) {
                 unconnectedInputs.delete(port);
@@ -196,3 +204,3 @@ const resolution = magicInputResolutions.get(port);
             }
-            else {
+            else if ("node" in port) {
                 addEdge(visitNodeAndReturnItsId(port.node), port.name, outputNodeId, name, isConstant(output), !required);
@@ -249,4 +257,14 @@ }
         }
-        const { type, metadata } = node;
-        const thisNodeId = node.id ?? nextIdForType(type);
+        let type, metadata, thisNodeId;
+        if (isBoardInstance(node)) {
+            type = "invoke";
+            metadata = undefined;
+            thisNodeId = nextIdForType("invoke");
+        }
+        else {
+            const cast = node;
+            type = cast.type;
+            metadata = cast.metadata;
+            thisNodeId = cast.id ?? nextIdForType(type);
+        }
         const configuration = {};
@@ -268,7 +286,15 @@ descriptor = { id: thisNodeId, type, configuration };
         const configurationEntries = [];
-        for (const [portName, inputPort] of Object.entries(node.inputs)) {
+        if (isBoardInstance(node)) {
+            configurationEntries.push([
+                "$board",
+                `#${embedBoardAndReturnItsId(node.definition)}`,
+            ]);
+        }
+        for (const [portName, inputPort] of Object.entries(isBoardInstance(node) ? node.values : node.inputs)) {
             unconnectedInputs.delete(inputPort);
             const values = isConvergence(inputPort.value)
                 ? inputPort.value.ports
-                : [inputPort.value];
+                : inputPort.value
+                    ? [inputPort.value]
+                    : [inputPort];
             for (let value of values) {
@@ -287,2 +313,6 @@ let wasConstant = false;
                 }
+                if (isBoardOutput(value)) {
+                    addEdge(visitNodeAndReturnItsId(value.innerBoard), value.innerPortName, thisNodeId, portName, wasConstant, wasOptional);
+                    continue;
+                }
                 if (isLoopback(value)) {
@@ -325,3 +355,3 @@ value = value.value;
                     // value can never actually be undefined, right?
-                    throw new Error(`Internal error: value was undefined for a ${inputPort.node.type}:${inputPort.name} port.`);
+                    throw new Error(`Internal error: value was undefined for a ${inputPort.node?.type}:${inputPort.name} port.`);
                 }
@@ -342,2 +372,7 @@ else if (typeof value === "symbol") {
                 }
+                else if (typeof value === "object" &&
+                    value.constructor !== Object &&
+                    "value" in value) {
+                    configurationEntries.push([portName, value.value]);
+                }
                 else {
@@ -344,0 +379,0 @@ configurationEntries.push([

dist/internal/define/define.js

@@ -115,2 +115,4 @@ /**
     return Object.assign(impl.instantiate.bind(impl), {
+        breadboardType: "DiscreteComponent",
+        id: params.name,
         invoke: impl.invoke.bind(impl),
@@ -117,0 +119,0 @@ describe: impl.describe.bind(impl),

dist/internal/define/definition.d.ts

@@ -6,3 +6,3 @@ /**
  */
-import type { InputValues, NodeDescriberContext, NodeDescriberResult, NodeHandlerContext, OutputValues, Schema } from "@google-labs/breadboard";
+import type { InputValues, NodeDescriberContext, NodeDescriberResult, NodeHandlerContext, NodeHandlerMetadata, OutputValues, Schema } from "@google-labs/breadboard";
 import type { Input, InputWithDefault } from "../board/input.js";
@@ -27,4 +27,15 @@ import type { Loopback } from "../board/loopback.js";
 }> extends StrictNodeHandler {
+    breadboardType: "DiscreteComponent";
+    id: string;
+    metadata: NodeHandlerMetadata;
     <A extends LooseInstantiateArgs>(args: A & StrictInstantiateArgs<SI, OI, DI, A, IM>): Instance<InstanceInputs<SI, DI, A>, InstanceOutputs<SI, SO, DO, R, A>, R extends true ? undefined : DO, PI, PO, R>;
 }
+export type GenericDiscreteComponent = Definition<{
+    [K: string]: JsonSerializable;
+}, {
+    [K: string]: JsonSerializable;
+}, JsonSerializable | undefined, JsonSerializable | undefined, string, boolean, string | false, string | false, {
+    [K: string]: InputMetadata;
+}>;
+export declare function isDiscreteComponent(value: object): value is GenericDiscreteComponent;
 export declare class DefinitionImpl<SI extends {
@@ -31,0 +42,0 @@ [K: string]: JsonSerializable;

dist/internal/define/definition.js

@@ -14,2 +14,5 @@ /**
 import { normalizeBreadboardError } from "../common/error.js";
+export function isDiscreteComponent(value) {
+    return ("breadboardType" in value && value.breadboardType === "DiscreteComponent");
+}
 export class DefinitionImpl {
@@ -16,0 +19,0 @@ #name;

package.json

 {
   "name": "@breadboard-ai/build",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "JavaScript library for building boards and defining new node types for the Breadboard AI prototyping library",
@@ -76,3 +76,3 @@ "license": "Apache-2.0",
     "test": {
-      "command": "node --test --enable-source-maps --test-reporter spec dist/test/*_test.js",
+      "command": "find dist/test -name '*_test.js' | xargs node --test --enable-source-maps --test-reporter spec",
       "dependencies": [
@@ -85,3 +85,3 @@ "build:tsc"
     "test:only": {
-      "command": "node --test --test-only --enable-source-maps --test-reporter spec dist/test/*_test.js",
+      "command": "find dist/test -name '*_test.js' | xargs node --test --test-only --enable-source-maps --test-reporter spec",
       "dependencies": [
@@ -94,3 +94,3 @@ "build:tsc"
     "coverage": {
-      "command": "node --test --enable-source-maps --experimental-test-coverage --test-reporter lcov --test-reporter-destination=lcov.info dist/test/*_test.js",
+      "command": "find dist/test -name '*_test.js' | xargs node --test --enable-source-maps --experimental-test-coverage --test-reporter lcov --test-reporter-destination=lcov.info",
       "dependencies": [
@@ -121,7 +121,7 @@ "build:tsc"
   "dependencies": {
-    "@google-labs/breadboard": "^0.22.0",
+    "@google-labs/breadboard": "^0.23.0",
     "@types/json-schema": "^7.0.15"
   },
   "devDependencies": {
-    "@types/node": "^20.14.9",
+    "@types/node": "^20.14.12",
     "eslint": "^8.57.0",
@@ -128,0 +128,0 @@ "typescript": "^5.5.3",

No alert changes

Improved metrics

Total package byte prevSize

357981

9.1%

Number of package files

102

9.68%

Lines of code

3439

9.38%

Dependency changes

• + Added

  @google-labs/breadboard@0.23.0
  (transitive)

• - Removed

  @google-labs/breadboard@0.22.0
  (transitive)

• Updated

  @google-labs/breadboard@^0.23.0