Using unnest without cast?

[TinaNikou]

I found an example of using unnest from the core-kit in listFiles (./packages/google-drive-kit/src/components/list-files.ts) in the google-drive-kit, where it fetches from the API, then uses cast to pass in the raw response and the type, which is then passed to unnest:

const fileListType = object({
  kind: enumeration("drive#fileList"),
  nextPageToken: optional("string"),
  incompleteSearch: "boolean",
  files: array(fileType),
});
...
const rawResponse = fetch({ url, headers });
const response = cast(rawResponse, fileListType);
const { files, incompleteSearch, nextPageToken } = unnest(response);

I was wondering if it's intended for cast to be required or not when using unnest, and if so then how? I thought that unnest might be able to handle the types and JSON automatically without using cast first, but I can't seem to get it to work.

I tried it with and without using cast on the Nager Date Country Info API board (code below) and it works when using cast but without, then it errors Error: Expected schema.type to be "object" but was "array,boolean,null,number,object,string".

import { board, enumeration, input } from "@breadboard-ai/build";
import { fetch, unnest } from "@google-labs/core-kit";
import { urlTemplate } from "@google-labs/template-kit";
import { countryCodes } from "../../../utils/countryCodes";

const countryCodeInput = input({
  title: "countryCode",
  type: enumeration(...countryCodes),
  description: "The data for countryCode",
  default: "US"
});

const url = urlTemplate({
  $id: "url",
  template: "https://date.nager.at/api/v3/CountryInfo/{countryCode}",
  countryCode: countryCodeInput
});

const rawResponse = fetch({
  $id: "fetchResult",
  method: "GET",
  url: url.outputs.url,
});

// const response = cast(rawResponse, object({
//   commonName: "string",
//   officialName: "string",
//   countryCode: "string",
//   region: "string",
//   borders: array(object({}))
// })); // Passing this into `unnest` works

const { commonName, officialName, countryCode, region, borders } = unnest(rawResponse); // Error

export default board({
  title: "Nager Date Country Info API",
  inputs: { countryCode: countryCodeInput },
  outputs: { commonName, officialName, countryCode, region, borders },
});

[aomarks]

Yep, unnest requires that the value you wire to it has a schema, and that the schema has type object. cast is the best way to assign a schema to some value when it's unknown, such as in the case of fetch. In other situations where there is already a schema, you wouldn't need the cast.

[aomarks]

Why I don't think it's a good idea to infer schema from values:

1. It means that you have to actually execute the board before you can know anything about the schema, which means you can't do anything useful with types until runtime, which is quite limiting.

2. Inferring schema from values is error-prone, because you are only seeing one possible value at a time. It's pretty common for APIs to return different shaped data depending on their inputs. The schema of a port should reflect all possible values on that port, not just one of them.

[TinaNikou]

That all makes a lot of sense! Thank you 💖