@react-native-firebase/firestore 23.8.6 → 24.0.0

package/lib/pipelines/index.ts

@@ -0,0 +1,203 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import type { PipelineSource } from './pipeline-source';
+import type { Pipeline } from './pipeline';
+import { installPipelineRuntime, registerPipelineRuntimeInstaller } from './pipeline_runtime';
+
+/**
+ * @beta
+ * Pipeline type for Firestore pipelines API.
+ */
+export type { PipelineResult, PipelineSnapshot } from './pipeline-result';
+export type { Pipeline } from './pipeline';
+export type { PipelineSource } from './pipeline-source';
+
+export type {
+  BooleanExpression,
+  Selectable,
+  Field,
+  Expression,
+  FunctionExpression,
+  AggregateFunction,
+  ExpressionType,
+  Type,
+  TimeGranularity,
+  AliasedAggregate,
+  AliasedExpression,
+} from './expressions';
+export type {
+  StageOptions,
+  AddFieldsStageOptions,
+  AggregateStageOptions,
+  CollectionGroupStageOptions,
+  CollectionStageOptions,
+  DatabaseStageOptions,
+  DistinctStageOptions,
+  DocumentsStageOptions,
+  FindNearestStageOptions,
+  LimitStageOptions,
+  OffsetStageOptions,
+  RemoveFieldsStageOptions,
+  ReplaceWithStageOptions,
+  SampleStageOptions,
+  SelectStageOptions,
+  SortStageOptions,
+  UnionStageOptions,
+  UnnestStageOptions,
+  WhereStageOptions,
+} from './stage_options';
+export type { PipelineExecuteOptions } from './pipeline_options';
+export type { OneOf } from './types';
+
+export { execute } from './pipeline_impl';
+export {
+  field,
+  and,
+  or,
+  greaterThan,
+  equal,
+  notEqual,
+  greaterThanOrEqual,
+  lessThan,
+  lessThanOrEqual,
+  exists,
+  arrayContains,
+  arrayContainsAny,
+  arrayContainsAll,
+  startsWith,
+  endsWith,
+  OrderingHelper as Ordering,
+  ascending,
+  descending,
+  countAll,
+  map,
+  array,
+  constant,
+  add,
+  subtract,
+  divide,
+  multiply,
+  documentId,
+  sum,
+  count,
+  average,
+  abs,
+  ceil,
+  floor,
+  mod,
+  round,
+  conditional,
+  countDistinct,
+  first,
+  last,
+  arrayAgg,
+  concat,
+  sqrt,
+  currentTimestamp,
+  not,
+  ifAbsent,
+  ifError,
+  toLower,
+  toUpper,
+  trim,
+  substring,
+  arrayAggDistinct,
+  arrayConcat,
+  arrayGet,
+  arrayLength,
+  arraySum,
+  byteLength,
+  charLength,
+  collectionId,
+  countIf,
+  exp,
+  join,
+  like,
+  ln,
+  log,
+  log10,
+  maximum,
+  minimum,
+  pow,
+  reverse,
+  split,
+  cosineDistance,
+  dotProduct,
+  equalAny,
+  euclideanDistance,
+  isAbsent,
+  isError,
+  isType,
+  logicalMaximum,
+  logicalMinimum,
+  ltrim,
+  notEqualAny,
+  rand,
+  rtrim,
+  stringConcat,
+  mapEntries,
+  mapGet,
+  mapKeys,
+  mapMerge,
+  mapRemove,
+  mapSet,
+  mapValues,
+  regexContains,
+  regexFind,
+  regexFindAll,
+  regexMatch,
+  stringContains,
+  stringIndexOf,
+  stringRepeat,
+  stringReplaceAll,
+  stringReplaceOne,
+  stringReverse,
+  timestampAdd,
+  timestampSubtract,
+  timestampToUnixMicros,
+  timestampToUnixMillis,
+  timestampToUnixSeconds,
+  timestampTruncate,
+  trunc,
+  type,
+  unixMicrosToTimestamp,
+  unixMillisToTimestamp,
+  unixSecondsToTimestamp,
+  vectorLength,
+  xor,
+  length,
+} from './expressions';
+export { pipelineResultEqual } from './pipeline-result';
+
+registerPipelineRuntimeInstaller();
+installPipelineRuntime();
+
+declare module '../types/firestore' {
+  /**
+   * @beta
+   * Creates and returns a new PipelineSource, which allows specifying the source stage of a `Pipeline`.
+   *
+   * @example
+   * ```
+   * const myPipeline = firestore.pipeline().collection('books');
+   * ```
+   */
+  interface Firestore {
+    pipeline(): PipelineSource<Pipeline>;
+  }
+}

package/lib/pipelines/pipeline-result.ts

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import type { DocumentData, DocumentReference } from '../types/firestore';
+import type Timestamp from '../FirestoreTimestamp';
+import type { FieldPath } from '../modular/FieldPath';
+import type { Field } from './expressions';
+
+/**
+ * @beta
+ * Result of running a pipeline. One per document (or per group with aggregation, or single for global aggregation).
+ */
+export interface PipelineResult<T = DocumentData> {
+  data(): T;
+  get(fieldPath: string | FieldPath | Field): unknown;
+  readonly ref?: DocumentReference;
+  readonly id?: string;
+  readonly createTime?: Timestamp;
+  readonly updateTime?: Timestamp;
+}
+
+/**
+ * @beta
+ * Snapshot returned from `execute(pipeline)`.
+ */
+export interface PipelineSnapshot<T = DocumentData> {
+  readonly results: PipelineResult<T>[];
+  readonly executionTime: Timestamp;
+}
+
+/**
+ * @beta
+ * Compares two pipeline results for equality.
+ */
+export function pipelineResultEqual(left: PipelineResult, right: PipelineResult): boolean {
+  if (left === right) {
+    return true;
+  }
+
+  const leftRefPath = left.ref?.path;
+  const rightRefPath = right.ref?.path;
+
+  if (leftRefPath !== rightRefPath) {
+    return false;
+  }
+
+  if (left.id !== right.id) {
+    return false;
+  }
+
+  const leftCreateTime = left.createTime?.toMillis();
+  const rightCreateTime = right.createTime?.toMillis();
+  if (leftCreateTime !== rightCreateTime) {
+    return false;
+  }
+
+  const leftUpdateTime = left.updateTime?.toMillis();
+  const rightUpdateTime = right.updateTime?.toMillis();
+  if (leftUpdateTime !== rightUpdateTime) {
+    return false;
+  }
+
+  return JSON.stringify(left.data()) === JSON.stringify(right.data());
+}

package/lib/pipelines/pipeline-source.ts

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import type { CollectionReference, DocumentReference, Query } from '../types/firestore';
+import type { Pipeline } from './pipeline';
+
+/**
+ * @beta
+ * Source stage options for collection.
+ *
+ * Note: `rawOptions` are currently applied on Android and web only. iOS rejects them because the
+ * native Firestore pipeline SDK does not yet expose collection source options.
+ */
+export interface PipelineCollectionSourceOptions {
+  path?: string;
+  collectionRef?: CollectionReference;
+  rawOptions?: { [name: string]: unknown };
+}
+
+/**
+ * @beta
+ * Source stage options for collectionGroup.
+ *
+ * Note: `rawOptions` are currently applied on Android and web only. iOS rejects them because the
+ * native Firestore pipeline SDK does not yet expose collection group source options.
+ */
+export interface PipelineCollectionGroupSourceOptions {
+  collectionId?: string;
+  rawOptions?: { [name: string]: unknown };
+}
+
+/**
+ * @beta
+ * Source stage options for database.
+ *
+ * Note: `rawOptions` are currently applied on Android and web only. iOS rejects them because the
+ * native Firestore pipeline SDK does not yet expose database source options.
+ */
+export interface PipelineDatabaseSourceOptions {
+  rawOptions?: { [name: string]: unknown };
+}
+
+/**
+ * @beta
+ * Source stage options for documents.
+ */
+export interface PipelineDocumentsSourceOptions {
+  docs?: Array<string | DocumentReference>;
+}
+
+/**
+ * @beta
+ * PipelineSource defines the input for a pipeline. Call exactly one of collection, collectionGroup, database, documents, or createFrom.
+ */
+export interface PipelineSource<TPipeline extends Pipeline = Pipeline> {
+  collection(path: string): TPipeline;
+  collection(collectionRef: CollectionReference): TPipeline;
+  collection(options: PipelineCollectionSourceOptions): TPipeline;
+
+  collectionGroup(collectionId: string): TPipeline;
+  collectionGroup(options: PipelineCollectionGroupSourceOptions): TPipeline;
+
+  database(options?: PipelineDatabaseSourceOptions): TPipeline;
+
+  documents(docs: Array<string | DocumentReference>): TPipeline;
+  documents(options: PipelineDocumentsSourceOptions): TPipeline;
+
+  createFrom(query: Query): TPipeline;
+}

package/lib/pipelines/pipeline.ts

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import type {
+  PipelineAggregateOptions,
+  PipelineDistinctOptions,
+  PipelineFindNearestOptions,
+  PipelineReplaceWithOptions,
+  PipelineSampleOptions,
+  PipelineUnionOptions,
+  PipelineUnnestOptions,
+  PipelineRawStageOptions,
+} from './stage_options';
+import type {
+  BooleanExpression,
+  Selectable,
+  Field,
+  Ordering,
+  AliasedAggregate,
+} from './expressions';
+import type { DocumentData } from '../types/firestore';
+import type { FirestorePipelineSerializedInternal } from '../types/internal';
+
+/** @internal Serialized pipeline payload shape forwarded to native/web executors. */
+export type SerializedPipeline = FirestorePipelineSerializedInternal;
+
+/**
+ * @beta
+ * Pipeline with chained stages. Each stage returns a new Pipeline (immutable chain).
+ */
+export interface Pipeline<T = DocumentData> {
+  /**
+   * @internal
+   * Serializes the source + stage chain to the wire format.
+   */
+  serialize(): SerializedPipeline;
+
+  where(condition: BooleanExpression): Pipeline<T>;
+  where(options: { condition: BooleanExpression }): Pipeline<T>;
+
+  select(...selection: (Selectable | string)[]): Pipeline<T>;
+  select(options: { selection: (Selectable | string)[] }): Pipeline<T>;
+
+  addFields(...field: Selectable[]): Pipeline<T>;
+  addFields(options: { field: Selectable[] }): Pipeline<T>;
+
+  removeFields(...field: (Field | string)[]): Pipeline<T>;
+  removeFields(options: { field: (Field | string)[] }): Pipeline<T>;
+
+  sort(...ordering: Ordering[]): Pipeline<T>;
+  sort(options: { ordering: Ordering[] }): Pipeline<T>;
+
+  limit(n: number): Pipeline<T>;
+  limit(options: { n: number }): Pipeline<T>;
+
+  offset(n: number): Pipeline<T>;
+  offset(options: { n: number }): Pipeline<T>;
+
+  aggregate(...accumulator: AliasedAggregate[]): Pipeline<T>;
+  aggregate(options: PipelineAggregateOptions): Pipeline<T>;
+
+  distinct(...group: (Field | string)[]): Pipeline<T>;
+  distinct(options: PipelineDistinctOptions): Pipeline<T>;
+
+  findNearest(options: PipelineFindNearestOptions): Pipeline<T>;
+
+  replaceWith(fieldName: string): Pipeline<T>;
+  replaceWith(expr: Selectable): Pipeline<T>;
+  replaceWith(options: PipelineReplaceWithOptions): Pipeline<T>;
+
+  sample(n: number): Pipeline<T>;
+  sample(options: PipelineSampleOptions): Pipeline<T>;
+
+  union(otherPipeline: Pipeline<T>): Pipeline<T>;
+  union(options: PipelineUnionOptions<T>): Pipeline<T>;
+
+  unnest(selectable: Selectable, indexField?: string): Pipeline<T>;
+  unnest(options: PipelineUnnestOptions): Pipeline<T>;
+
+  rawStage(
+    name: string,
+    params: Record<string, unknown>,
+    options?: PipelineRawStageOptions,
+  ): Pipeline<T>;
+}

package/lib/pipelines/pipeline_impl.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import type { Pipeline } from './pipeline';
+import type { PipelineSnapshot } from './pipeline-result';
+import type { PipelineExecuteOptions } from './pipeline_options';
+import { executeRuntimePipeline } from './pipeline_runtime';
+
+/**
+ * @beta
+ * Executes a pipeline and returns a Promise that resolves to the pipeline snapshot.
+ *
+ * @example
+ * ```
+ * const snapshot = await execute(
+ *   firestore.pipeline().collection('books').where(gt(field('rating'), 4.5)).select('title', 'author', 'rating')
+ * );
+ * ```
+ */
+export function execute(pipeline: Pipeline): Promise<PipelineSnapshot>;
+
+/**
+ * @beta
+ * Executes a pipeline with options.
+ */
+export function execute(options: PipelineExecuteOptions): Promise<PipelineSnapshot>;
+
+export function execute(
+  pipelineOrOptions: Pipeline | PipelineExecuteOptions,
+): Promise<PipelineSnapshot> {
+  return executeRuntimePipeline(pipelineOrOptions);
+}

package/lib/pipelines/pipeline_options.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import type { Pipeline } from './pipeline';
+import type { StageOptions } from './stage_options';
+
+/**
+ * @beta
+ * Options for pipeline execute().
+ *
+ * Note: `indexMode` and `rawOptions` are currently applied on Android and web only. iOS rejects
+ * them because the native Firestore pipeline SDK does not yet expose execute options.
+ */
+export interface PipelineExecuteOptions extends StageOptions {
+  pipeline: Pipeline;
+  indexMode?: 'recommended';
+  rawOptions?: { [name: string]: unknown };
+}