feat(firestore): variable TS implementation

Author: russellwheatley

packages/firestore/lib/pipelines/expressions.ts

@@ -26,6 +26,7 @@ import type { Bytes } from '../modular/Bytes';
 export type ExpressionType =
   | 'Field'
   | 'Constant'
+  | 'Variable'
   | 'Function'
   | 'AggregateFunction'
   | 'ListOfExpressions'
@@ -148,11 +149,25 @@ export interface ConstantExpression extends FluentExpressionMethods {
   readonly _brand?: 'ConstantExpression';
 }
 
+/**
+ * @beta
+ * Variable expression returned by `variable(...)`.
+ */
+export interface VariableExpression extends Selectable, FluentExpressionMethods {
+  readonly _brand?: 'VariableExpression';
+}
+
 /**
  * @beta
  * Expression type for pipeline parameters (field refs, literals, function results).
  */
-export type Expression = Field | FunctionExpression | ConstantExpression | Selectable | string;
+export type Expression =
+  | Field
+  | FunctionExpression
+  | ConstantExpression
+  | VariableExpression
+  | Selectable
+  | string;
 
 /**
  * @beta
@@ -258,6 +273,7 @@ type BooleanExpressionNode = RuntimeExpressionNode & RuntimeExpressionMethods &
 type RuntimeExpressionFluentNode =
   | (RuntimeExpressionNode & RuntimeExpressionMethods & Field)
   | (RuntimeExpressionNode & RuntimeExpressionMethods & FunctionExpression)
+  | (RuntimeExpressionNode & RuntimeExpressionMethods & VariableExpression)
   | BooleanExpressionNode
   | ConstantExpressionNode;
 type FieldNode = RuntimeExpressionFluentNode & Field;
@@ -550,6 +566,16 @@ function createConstant(value: unknown): ConstantExpressionNode {
   });
 }
 
+function createVariable(name: unknown): RuntimeExpressionFluentNode & VariableExpression {
+  return createNode(expressionProto, {
+    [RUNTIME_NODE_SYMBOL]: true,
+    __kind: 'expression',
+    exprType: 'Variable',
+    selectable: true,
+    name: String(name ?? ''),
+  });
+}
+
 function normalizeMapLikeValue(value: Record<string, unknown>): Record<string, unknown> {
   const output: Record<string, unknown> = {};
 
@@ -842,6 +868,14 @@ export function field(_path: string): Field {
   return createField(_path);
 }
 
+/**
+ * @beta
+ * Returns a variable reference for alias-bound pipeline expressions.
+ */
+export function variable(_name: string): Expression {
+  return createVariable(_name);
+}
+
 /**
  * @beta
  * Logical AND of boolean expressions.
@@ -1004,9 +1038,6 @@ export function arrayContainsAll(
 /**
  * @beta
  * Filters an array using a provided alias and predicate expression.
- *
- * The alias is serialized for native/web SDKs that support variable-bound
- * predicates; RN Firebase does not yet expose the `variable()` helper.
  */
 export function arrayFilter(
   _fieldName: string,

packages/firestore/lib/pipelines/index.ts

@@ -67,6 +67,7 @@ export type { OneOf } from './types';
 export { execute } from './pipeline_impl';
 export {
   field,
+  variable,
   and,
   or,
   greaterThan,

packages/firestore/lib/types/internal.ts

@@ -110,6 +110,13 @@ export interface FirestorePipelineConstantExpressionInternal {
   value: FirestorePipelineSerializedValueInternal;
 }
 
+/** Serialized variable expression node passed to native pipeline execute bridge. */
+export interface FirestorePipelineVariableExpressionInternal {
+  __kind?: 'expression';
+  exprType: 'Variable';
+  name: string;
+}
+
 /** Serialized function expression node passed to native pipeline execute bridge. */
 export interface FirestorePipelineFunctionExpressionInternal {
   __kind?: 'expression';
@@ -160,6 +167,7 @@ export interface FirestorePipelineAliasedAggregateInternal {
 export type FirestorePipelineExpressionInternal =
   | FirestorePipelineFieldExpressionInternal
   | FirestorePipelineConstantExpressionInternal
+  | FirestorePipelineVariableExpressionInternal
   | FirestorePipelineFunctionExpressionInternal;
 
 export type FirestorePipelineSelectableInternal =

packages/firestore/lib/web/pipelines/pipeline_node_builder.ts

@@ -57,6 +57,7 @@ function isExpressionNode(value: Record<string, unknown>): boolean {
     value.__kind === 'expression' ||
     value.exprType === 'Field' ||
     value.exprType === 'Constant' ||
+    value.exprType === 'Variable' ||
     value.exprType === 'Function'
   );
 }
@@ -168,6 +169,11 @@ function rebuildExpressionNode(
     return;
   }
 
+  if (node.exprType === 'Variable' && typeof node.name === 'string') {
+    resolve(getPipelineHelper('variable')(node.name) as Expression);
+    return;
+  }
+
   if (typeof node.name === 'string') {
     const helperName = node.name;
     const args = Array.isArray(node.args) ? node.args : [];