@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/src/firestore/internal/firestoreValueWalk.ts

@@ -0,0 +1,349 @@
+/**
+ * The one walk over Firestore Values that the guard and both SDK mappings
+ * share: the path to each value, the scalars, arrays and maps, and how a
+ * value outside the union is reported. What differs per SDK is only how each
+ * kind of value in {@link kinds} becomes the SDK's own, and back.
+ */
+import { Equal, Result } from "effect";
+import { FirestoreError } from "./firestoreError.ts";
+import type * as FirestoreValue from "../FirestoreValue.ts";
+import * as documentPath from "./documentPath.ts";
+import * as fieldValue from "./fieldValue.ts";
+import * as geoPoint from "./geoPoint.ts";
+import * as timestamp from "./timestamp.ts";
+
+/** @internal */
+export type FieldPath = ReadonlyArray<string | number>;
+
+/** @internal */
+export const formatFieldPath = (path: FieldPath): string =>
+  path.length === 0
+    ? "the document"
+    : `"${path
+        .map((key, i) => (typeof key === "number" ? `[${key}]` : i === 0 ? key : `.${key}`))
+        .join("")}"`;
+
+/**
+ * The kinds of Firestore Value other than scalars, arrays and maps, each with
+ * the guard that recognises it. Adding a kind here makes every SDK's
+ * {@link Writer} name it too.
+ */
+const kinds = {
+  bytes: (u: unknown): u is Uint8Array => u instanceof Uint8Array,
+  timestamp: timestamp.isTimestamp,
+  geoPoint: geoPoint.isGeoPoint,
+  documentPath: documentPath.isDocumentPath,
+  serverTimestamp: fieldValue.isServerTimestamp,
+  increment: fieldValue.isIncrement,
+  deleteField: fieldValue.isDeleteField,
+  arrayUnion: fieldValue.isArrayUnion,
+  arrayRemove: fieldValue.isArrayRemove,
+} as const;
+
+type Guarded<F> = F extends ((u: unknown) => u is infer A) ? A : never;
+
+/**
+ * Each kind of Firestore Value that is not a scalar, array or map, by name.
+ *
+ * @internal
+ */
+export type Kinds = { readonly [K in keyof typeof kinds]: Guarded<(typeof kinds)[K]> };
+
+const kindNames = Object.keys(kinds) as ReadonlyArray<keyof Kinds>;
+
+const kindOf = (u: object): keyof Kinds | undefined => kindNames.find((kind) => kinds[kind](u));
+
+/**
+ * Walks the value a kind holds, such as an array union's elements: `key` is
+ * where `child` sits within it.
+ *
+ * @internal
+ */
+export type Walk = (child: unknown, key: string | number) => unknown;
+
+/**
+ * How one SDK writes each kind of Firestore Value that is not a scalar, array
+ * or map.
+ *
+ * @internal
+ */
+export type Writer = {
+  readonly [K in keyof Kinds]: (value: Kinds[K], walk: Walk) => unknown;
+};
+
+/**
+ * How one SDK's values read back as Firestore Values. It hands back
+ * `undefined` for a value it leaves to the walk - a scalar, array or map -
+ * and calls `fail` for one of its own it cannot read.
+ *
+ * @internal
+ */
+export type Reader = (
+  value: object,
+  context: {
+    readonly walk: (child: unknown, key: string | number) => FirestoreValue.FirestoreValue;
+    readonly fail: (kind: string) => never;
+  },
+) => FirestoreValue.FirestoreValue | undefined;
+
+/** A map: a plain object whose keys are all strings. */
+const isMap = (u: object): u is Record<string, unknown> => {
+  const proto = Object.getPrototypeOf(u);
+  return (
+    (proto === Object.prototype || proto === null) && Object.getOwnPropertySymbols(u).length === 0
+  );
+};
+
+const describe = (u: object): string => {
+  const name = (u.constructor as { readonly name?: string } | undefined)?.name;
+  return name === undefined ? "an object with no prototype" : `a ${name}`;
+};
+
+/** A value outside the Firestore Value union, at `path`. */
+class Outside {
+  readonly kind: string;
+  readonly value: unknown;
+  readonly path: FieldPath;
+  constructor(kind: string, value: unknown, path: FieldPath) {
+    this.kind = kind;
+    this.value = value;
+    this.path = path;
+  }
+}
+
+const unhandled: unique symbol = Symbol("unhandled");
+
+/**
+ * Walks `value`, handing every object to `visit` first and then walking
+ * arrays and maps itself. Throws {@link Outside} at the first value that is
+ * none of these, or that contains itself.
+ */
+const walk = (
+  value: unknown,
+  visit: (
+    u: object,
+    walk: (child: unknown, key: string | number) => unknown,
+    fail: (kind: string) => never,
+  ) => unknown,
+): unknown => {
+  const path: Array<string | number> = [];
+  const ancestors = new Set<object>();
+  const within = (child: unknown, key: string | number): unknown => {
+    path.push(key);
+    try {
+      return go(child);
+    } finally {
+      path.pop();
+    }
+  };
+  const go = (u: unknown): unknown => {
+    switch (typeof u) {
+      case "boolean":
+      case "number":
+      case "string":
+        return u;
+      case "object":
+        break;
+      default:
+        throw new Outside(`a value of type ${typeof u}`, u, [...path]);
+    }
+    if (u === null) return u;
+    const fail = (kind: string): never => {
+      throw new Outside(kind, u, [...path]);
+    };
+    if (ancestors.has(u)) return fail("a value that contains itself");
+    ancestors.add(u);
+    try {
+      const out = visit(u, within, fail);
+      if (out !== unhandled) return out;
+      if (Array.isArray(u)) return u.map((e, i) => within(e, i));
+      if (isMap(u)) {
+        const map: Record<string, unknown> = {};
+        for (const key of Object.keys(u)) map[key] = within(u[key], key);
+        return map;
+      }
+      return fail(describe(u));
+    } finally {
+      ancestors.delete(u);
+    }
+  };
+  return go(value);
+};
+
+const write = (value: unknown, writer: Writer): unknown =>
+  walk(value, (u, within) => {
+    const kind = kindOf(u);
+    return kind === undefined ? unhandled : writer[kind](u as never, within);
+  });
+
+const keep = <A>(value: A): A => value;
+
+/** Builds nothing: walking with it only checks a value is a Firestore Value. */
+const checker: Writer = {
+  bytes: keep,
+  timestamp: keep,
+  geoPoint: keep,
+  documentPath: keep,
+  serverTimestamp: keep,
+  increment: keep,
+  deleteField: keep,
+  arrayUnion: (u, within) => u.elements.forEach(within),
+  arrayRemove: (u, within) => u.elements.forEach(within),
+};
+
+/** @internal */
+export const isFirestoreValue = (u: unknown): u is FirestoreValue.FirestoreValue => {
+  try {
+    write(u, checker);
+    return true;
+  } catch (e) {
+    if (e instanceof Outside) return false;
+    throw e;
+  }
+};
+
+/**
+ * Whether two Firestore Values are the same, as Firestore would store them:
+ * scalars by value, arrays and maps element by element and key by key, bytes
+ * byte by byte, and every other kind as that kind tells its values apart.
+ *
+ * @internal
+ */
+export const equals = (self: unknown, that: unknown): boolean => {
+  if (Object.is(self, that)) {
+    return true;
+  }
+  if (typeof self !== "object" || typeof that !== "object" || self === null || that === null) {
+    return false;
+  }
+  if (Array.isArray(self) || Array.isArray(that)) {
+    return (
+      Array.isArray(self) &&
+      Array.isArray(that) &&
+      self.length === that.length &&
+      self.every((element, i) => equals(element, that[i]))
+    );
+  }
+  const kind = kindOf(self);
+  if (kind !== kindOf(that)) {
+    return false;
+  }
+  switch (kind) {
+    case undefined:
+      return (
+        isMap(self) &&
+        isMap(that) &&
+        Object.keys(self).length === Object.keys(that).length &&
+        Object.keys(self).every((key) => Object.hasOwn(that, key) && equals(self[key], that[key]))
+      );
+    case "bytes": {
+      const a = self as Uint8Array;
+      const b = that as Uint8Array;
+      return a.length === b.length && a.every((byte, i) => byte === b[i]);
+    }
+    case "arrayUnion":
+    case "arrayRemove":
+      return equals((self as Kinds["arrayUnion"]).elements, (that as Kinds["arrayUnion"]).elements);
+    default:
+      return Equal.equals(self, that);
+  }
+};
+
+/**
+ * Turns a Firestore Value into an SDK's own value through `writer`. A value
+ * outside the union is a defect, since `toCodecFirestore` only ever encodes
+ * Firestore Values.
+ *
+ * @internal
+ */
+export const toSdk = (value: FirestoreValue.FirestoreValue, writer: Writer): unknown => {
+  try {
+    return write(value, writer);
+  } catch (e) {
+    if (!(e instanceof Outside)) throw e;
+    throw new globalThis.Error(
+      `Cannot write ${e.kind} at ${formatFieldPath(e.path)}, which is not a Firestore Value`,
+      { cause: e.value },
+    );
+  }
+};
+
+/**
+ * Turns what an SDK read into a Firestore Value through `reader`, failing on
+ * a value outside the union, such as a vector, and naming the field that
+ * holds it.
+ *
+ * @internal
+ */
+export const fromSdk = (
+  value: unknown,
+  reader: Reader,
+): Result.Result<FirestoreValue.FirestoreValue, FirestoreError> => {
+  try {
+    return Result.succeed(
+      walk(value, (u, within, fail) => {
+        const out = reader(u, {
+          walk: within as (child: unknown, key: string | number) => FirestoreValue.FirestoreValue,
+          fail,
+        });
+        return out === undefined ? unhandled : out;
+      }) as FirestoreValue.FirestoreValue,
+    );
+  } catch (e) {
+    if (!(e instanceof Outside)) throw e;
+    return Result.fail(
+      new FirestoreError({
+        message: `Firestore holds ${e.kind} at ${formatFieldPath(e.path)}, which is not a Firestore Value`,
+        code: undefined,
+        cause: e.value,
+      }),
+    );
+  }
+};
+
+/**
+ * Reads what an SDK holds for the document at `path` as Firestore Values
+ * through `reader`, keeping `undefined` - a document that is not there - as
+ * it is.
+ *
+ * @internal
+ */
+export const readDocument = (
+  path: string,
+  data: unknown,
+  reader: Reader,
+): Result.Result<FirestoreValue.FirestoreValue | undefined, FirestoreError> =>
+  data === undefined
+    ? Result.succeed(undefined)
+    : Result.mapError(
+        fromSdk(data, reader),
+        (error) =>
+          new FirestoreError({
+            message: `Failed to read the document "${path}": ${error.message}`,
+            code: undefined,
+            cause: error.cause,
+          }),
+      );
+
+/**
+ * Reads Firestore Values as they are, walking into the values a kind holds,
+ * so that only a value outside the union fails.
+ */
+const asIs: Reader = (u, { walk }) => {
+  const kind = kindOf(u);
+  if (kind === "arrayUnion" || kind === "arrayRemove") {
+    (u as Kinds["arrayUnion"]).elements.forEach((element, i) => walk(element, i));
+  }
+  return kind === undefined ? undefined : (u as FirestoreValue.FirestoreValue);
+};
+
+/**
+ * Checks that what a backend read for the document at `path` is made of
+ * Firestore Values, failing as {@link readDocument} does on one that is not.
+ * It hands back `data` itself, so `undefined` - a document that is not there -
+ * stays as it is.
+ *
+ * @internal
+ */
+export const checkDocument = <A>(path: string, data: A): Result.Result<A, FirestoreError> =>
+  Result.map(readDocument(path, data, asIs), () => data);

package/src/firestore/internal/geoPoint.ts

@@ -0,0 +1,59 @@
+import { Equal, Hash, Inspectable, Option, Predicate } from "effect";
+import type * as GeoPoint from "../GeoPoint.ts";
+
+/** @internal */
+export const TypeId = "~@visiolab/effect-firebase/firestore/GeoPoint";
+
+/** Kept apart from the guards below, which narrow a `number` to `never`. */
+const inLatitudeRange = (n: number): boolean => Number.isFinite(n) && n >= -90 && n <= 90;
+
+const inLongitudeRange = (n: number): boolean => Number.isFinite(n) && n >= -180 && n <= 180;
+
+/** @internal */
+export const isGeoPoint = (u: unknown): u is GeoPoint.GeoPoint =>
+  Predicate.hasProperty(u, TypeId) &&
+  u[TypeId] === TypeId &&
+  Predicate.hasProperty(u, "latitude") &&
+  Predicate.hasProperty(u, "longitude") &&
+  Predicate.isNumber(u.latitude) &&
+  Predicate.isNumber(u.longitude) &&
+  inLatitudeRange(u.latitude) &&
+  inLongitudeRange(u.longitude);
+
+const Proto: Omit<GeoPoint.GeoPoint, "latitude" | "longitude"> = {
+  ...Inspectable.BaseProto,
+  [TypeId]: TypeId,
+  toJSON(this: GeoPoint.GeoPoint) {
+    return { _id: "GeoPoint", latitude: this.latitude, longitude: this.longitude };
+  },
+  [Equal.symbol](this: GeoPoint.GeoPoint, that: unknown): boolean {
+    return isGeoPoint(that) && this.latitude === that.latitude && this.longitude === that.longitude;
+  },
+  [Hash.symbol](this: GeoPoint.GeoPoint): number {
+    return Hash.combine(Hash.number(this.latitude), Hash.number(this.longitude));
+  },
+};
+
+const makeUnchecked = (latitude: number, longitude: number): GeoPoint.GeoPoint =>
+  Object.assign(Object.create(Proto) as typeof Proto, { latitude, longitude });
+
+/** @internal */
+export const makeUnsafe = (latitude: number, longitude: number): GeoPoint.GeoPoint => {
+  if (!inLatitudeRange(latitude)) {
+    throw new Error(
+      `Invalid Firestore geopoint: latitude must be a number between -90 and 90, got ${latitude}`,
+    );
+  }
+  if (!inLongitudeRange(longitude)) {
+    throw new Error(
+      `Invalid Firestore geopoint: longitude must be a number between -180 and 180, got ${longitude}`,
+    );
+  }
+  return makeUnchecked(latitude, longitude);
+};
+
+/** @internal */
+export const make = (latitude: number, longitude: number): Option.Option<GeoPoint.GeoPoint> =>
+  inLatitudeRange(latitude) && inLongitudeRange(longitude)
+    ? Option.some(makeUnchecked(latitude, longitude))
+    : Option.none();

package/src/firestore/internal/patch.ts

@@ -0,0 +1,21 @@
+import { Inspectable, Predicate } from "effect";
+import type * as Patch from "../Patch.ts";
+
+/** @internal */
+export const ReplaceTypeId = "~@visiolab/effect-firebase/firestore/Patch/Replace";
+
+const ReplaceProto: Omit<Patch.Replace<unknown>, "value"> = {
+  ...Inspectable.BaseProto,
+  [ReplaceTypeId]: ReplaceTypeId,
+  toJSON(this: Patch.Replace<unknown>) {
+    return { _id: "Replace", value: Inspectable.toJson(this.value) };
+  },
+};
+
+/** @internal */
+export const isReplace = (u: unknown): u is Patch.Replace<unknown> =>
+  Predicate.hasProperty(u, ReplaceTypeId);
+
+/** @internal */
+export const replace = <const A>(value: A): Patch.Replace<A> =>
+  Object.assign(Object.create(ReplaceProto) as typeof ReplaceProto, { value });

package/src/firestore/internal/querySnapshot.ts

@@ -0,0 +1,39 @@
+import { Inspectable, Predicate } from "effect";
+import type * as Collection from "../Collection.ts";
+import type * as DocumentSnapshot from "../DocumentSnapshot.ts";
+import type * as QuerySnapshot from "../QuerySnapshot.ts";
+import { attach, extraToJson, type WithExtra } from "./snapshotExtra.ts";
+
+/** @internal */
+export const TypeId = "~@visiolab/effect-firebase/firestore/QuerySnapshot";
+
+/** @internal */
+export const isQuerySnapshot = (u: unknown): u is QuerySnapshot.QuerySnapshot<Collection.Any> =>
+  Predicate.hasProperty(u, TypeId);
+
+interface QuerySnapshotImpl extends WithExtra {
+  readonly docs: ReadonlyArray<DocumentSnapshot.Existing<Collection.Any>>;
+}
+
+const QuerySnapshotProto = {
+  ...Inspectable.BaseProto,
+  [TypeId]: TypeId,
+  toJSON(this: QuerySnapshotImpl) {
+    return {
+      _id: "QuerySnapshot",
+      docs: this.docs.map((doc) => doc.toJSON()),
+      ...extraToJson(this),
+    };
+  },
+};
+
+/** @internal */
+export const make = <C extends Collection.Any>(
+  docs: ReadonlyArray<DocumentSnapshot.Existing<C>>,
+  extra?: object,
+): QuerySnapshot.QuerySnapshot<C> => {
+  const self = Object.assign(Object.create(QuerySnapshotProto) as typeof QuerySnapshotProto, {
+    docs,
+  });
+  return attach(self, extra) as unknown as QuerySnapshot.QuerySnapshot<C>;
+};

package/src/firestore/internal/schemaAST.ts

@@ -0,0 +1,83 @@
+/**
+ * The one place this package reaches into Effect's `@internal` `SchemaAST`
+ * helpers.
+ *
+ * Effect has no public way to define a canonical format, so deriving
+ * `toCodecFirestore` the way `toCodecJson` is derived needs the same internal
+ * helpers Effect uses for it (ADR 0002). They exist at runtime but are stripped
+ * from Effect's type declarations, so each is typed here by hand, against the
+ * pinned `effect` version. Keeping them together means a future public API for
+ * canonical formats is a swap of this module only.
+ */
+import { SchemaAST } from "effect";
+
+interface Internals {
+  readonly replaceEncoding: <A extends SchemaAST.AST>(
+    ast: A,
+    encoding: SchemaAST.Encoding | undefined,
+  ) => A;
+  readonly mapLink: (
+    link: SchemaAST.Link,
+    f: (ast: SchemaAST.AST) => SchemaAST.AST,
+  ) => SchemaAST.Link;
+  readonly replaceContextLastLink: <A extends SchemaAST.AST>(
+    ast: A,
+    context: SchemaAST.Context,
+  ) => A;
+  readonly applyToSelfOrLastLinkEncodingIdempotent: (
+    f: (ast: SchemaAST.AST) => SchemaAST.AST,
+  ) => (ast: SchemaAST.AST) => SchemaAST.AST;
+  readonly parameterFromString: (ast: SchemaAST.AST) => SchemaAST.AST;
+}
+
+const internals = SchemaAST as unknown as Internals;
+
+/** Replaces the encoding chain of `ast`, leaving `ast` alone when it is the same. */
+export const replaceEncoding = internals.replaceEncoding;
+
+/** Maps the target of `link`, leaving `link` alone when the target is unchanged. */
+export const mapLink = internals.mapLink;
+
+/** Replaces the context of the last link's target. */
+export const replaceContextLastLink = internals.replaceContextLastLink;
+
+/**
+ * Applies `f` to the node itself when it has no encoding, or to the target of
+ * its last encoding link otherwise, so user transformations run first. The
+ * result is memoized per node.
+ */
+export const applyToSelfOrLastLinkEncodingIdempotent =
+  internals.applyToSelfOrLastLinkEncodingIdempotent;
+
+/** How a canonical format reads index-signature and property keys back from strings. */
+export const parameterFromString = internals.parameterFromString;
+
+/** The keywords whose canonical JSON form Effect derives itself. */
+type JsonKeyword =
+  | SchemaAST.Undefined
+  | SchemaAST.Void
+  | SchemaAST.Literal
+  | SchemaAST.Number
+  | SchemaAST.Symbol
+  | SchemaAST.UniqueSymbol
+  | SchemaAST.BigInt;
+
+/** The keyword's own canonical JSON codec, as `toCodecJson` derives it. */
+export const keywordToCodecJson = (ast: JsonKeyword): SchemaAST.AST =>
+  (ast as unknown as { toCodecJson(): SchemaAST.AST }).toCodecJson();
+
+/** The keyword's own canonical StringTree codec, as `toCodecStringTree` derives it. */
+export const keywordToCodecStringTree = (ast: JsonKeyword): SchemaAST.AST =>
+  (ast as unknown as { toCodecStringTree(): SchemaAST.AST }).toCodecStringTree();
+
+/** Recurs into the members of a composite node. */
+export const recur = <A extends SchemaAST.AST>(
+  ast: A,
+  f: (ast: SchemaAST.AST) => SchemaAST.AST,
+  onKey?: (ast: SchemaAST.AST) => SchemaAST.AST,
+): A =>
+  (
+    ast as unknown as {
+      recur(f: (ast: SchemaAST.AST) => SchemaAST.AST, onKey?: unknown): A;
+    }
+  ).recur(f, onKey);

package/src/firestore/internal/snapshotExtra.ts

@@ -0,0 +1,47 @@
+import { Inspectable } from "effect";
+
+/**
+ * Where a snapshot keeps the extra an SDK built it with, so that it can show
+ * that extra when it prints without telling the extra's fields from its own.
+ */
+const ExtraKey = "~@visiolab/effect-firebase/firestore/SnapshotExtra";
+
+/** @internal */
+export interface WithExtra {
+  readonly [ExtraKey]?: object;
+}
+
+/**
+ * `self` with the fields of `extra` on it, remembered as its extra so that
+ * {@link extraToJson} shows them.
+ *
+ * The extra itself is held on a key that is not enumerable, so that it does
+ * not show up twice: its fields are already on the snapshot.
+ *
+ * @internal
+ */
+export const attach = <A extends object>(self: A, extra: object | undefined): A => {
+  if (extra === undefined) {
+    return self;
+  }
+  Object.defineProperty(self, ExtraKey, { value: extra });
+  return Object.assign(self, extra);
+};
+
+/**
+ * How the extra `self` was built with prints: each of its fields as it would
+ * print on its own, or nothing when it was built without one.
+ *
+ * @internal
+ */
+export const extraToJson = (self: WithExtra): Record<string, unknown> => {
+  const extra = self[ExtraKey];
+  if (extra === undefined) {
+    return {};
+  }
+  const json: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(extra)) {
+    json[key] = Inspectable.toJson(value);
+  }
+  return json;
+};

package/src/firestore/internal/streamFromListener.ts

@@ -0,0 +1,27 @@
+import { Cause, Effect, Queue, Result, Stream } from "effect";
+import type * as Firestore from "../Firestore.ts";
+import type { FirestoreError } from "./firestoreError.ts";
+
+/** @internal */
+export const streamFromListener = <S, A>(
+  options: Firestore.StreamFromListenerOptions<S, A>,
+): Stream.Stream<A, FirestoreError> =>
+  Stream.callback<A, FirestoreError>(
+    (queue) =>
+      Effect.acquireRelease(
+        Effect.sync(() =>
+          options.subscribe(
+            (snapshot) => {
+              // Runs inside the SDK's listener, so a snapshot that does not map
+              // fails the stream rather than throwing back into the SDK.
+              const element = options.map(snapshot);
+              if (Result.isSuccess(element)) Queue.offerUnsafe(queue, element.success);
+              else Queue.failCauseUnsafe(queue, Cause.fail(element.failure));
+            },
+            (error) => Queue.failCauseUnsafe(queue, Cause.fail(options.onError(error))),
+          ),
+        ),
+        (unsubscribe) => Effect.sync(unsubscribe),
+      ),
+    { bufferSize: 1, strategy: "sliding" },
+  );