Below contains an overview of the specifications for the Bundle Builder API, including TypeScript definitions & detailed descriptions.
BundleDocument Interface
The specification for a single document within the configured collection:
type BundleDocument = { // A list of document IDs to serve in the bundle. docs?: Array<string>; // A map containing individual named queries and their definitions. queries?: Map<string, QueryDefinition[]>; // A map of parameters and their definitions, which can be provided to a query definition. params?: Map<string, ParamDefinition>; // Specifies how long to keep the bundle in the client's cache, in seconds. If not defined, client-side cache is disabled. clientCache?: string; // Only used in combination with Firebase Hosting. Specifies how long to keep the bundle in Firebase Hosting CDN cache, in seconds. serverCache: string; // Specifies how long (in seconds) to keep the bundle in a Cloud Storage bucket, in seconds. If not defined, Cloud Storage bucket is not accessed. fileCache?: string; // If a 'File Cache' is specified, bundles created before this timestamp will not be file cached. notBefore?: Timestamp; }; ParamDefinition Interface
The specification of a single parameter defined in a BundleDocument.
type ParamDefinition = { // Whether this parameter is required. If not provided as a query string, an error will be thrown. required: boolean; // The type of value which will be parsed, defaults to 'string'. type?: | "string" | "integer" | "float" | "boolean" | "string-array" | "integer-array" | "float-array"; }; For example, given the follow parameter:
params: { name: { required: true, type: 'string', } } When making a request to the bundle HTTP endpoint, the parameter can be provided via a query parameter, e.g. ?name=david. The parameter can be used within a QueryDefinition (see below) value ($name) to dynamically create bundles.
QueryDefinition Interface
A query definition is used to create named queries on the bundle. Each object within the queries map will create a new named query, using the object key as the name. Each query must specify a collection, and optionally a list of query conditions to perform.
type QueryDefinition = { // The collection to perform the query on. collection: string; // An optional list of conditions to perform on the specified collection. conditions?: QueryCondition[]; }; The conditions parameter can contain an array of QueryCondition interfaces. Each item in the array must only include a single condition.
type QueryCondition = { // Performs a `where` filter on the collection on a given FieldPath, operator and value. where?: [ string, ( | "<" | "<=" | "==" | ">=" | ">" | "!=" | "array-contains" | "in" | "not-in" | "array-contains-any" ), any ]; orderBy?: [string, ("asc" | "desc")?]; limit?: number; limitToLast?: number; offset?: number; startAt?: string; startAfter?: string; endAt?: string; endBefore?: string; }; For example, to create a query named "products" on a products collection with a where and limit condition, the data structure output should match the following:
queries: { products: { collection: 'products', conditions: [ { where: ['type', '==', 'featured'] }, { limit: 10 }, ], } } When providing array values to in, not-in, or array-contains-any filters, you must provide a comma separated value as the value as nested array values are not supported in Firestore. For example:
{ where: ['category', 'in', 'womens,shorts'] }, // ['womens', 'shorts'] Any number value will be parsed as a number, however if a string number value is required it should be wrapped in parentheses:
{ where: ['price', 'in', '1,2.5'] }, // [1, 2.5] { where: ['price', 'in', '"1","2.5"'] }, // ['1', '2.5'] Conditions can also be used alongside parameters. For example, if a parameter type is defined (see above), this can be provided to a condition value to provide dynamic data bundles via the $ syntax:
// ?type=featured conditions: [ { where: ['type', '==', '$type'] },