@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/dist/firestore/Timestamp.d.mts

@@ -0,0 +1,273 @@
+import { DateTime, Effect, Equal, Inspectable, Option, Order as Order$1 } from "effect";
+declare namespace Timestamp_d_exports {
+  export { Order, Timestamp, fromDateTime, fromDateTimeUnsafe, fromMillis, fromMillisUnsafe, isTimestamp, make, makeUnsafe, now, toDateTime, toMillis };
+}
+declare const TypeId = "~@visiolab/effect-firebase/firestore/Timestamp";
+/**
+ * An instant, stored the way Firestore stores it.
+ *
+ * **When to use**
+ *
+ * Use when a document is read, written back, and has to come out unchanged.
+ * Firestore keeps timestamps to the microsecond, which `DateTime.Utc` and
+ * `Date` cannot hold, so this is the only representation that round-trips
+ * exactly.
+ *
+ * **Details**
+ *
+ * Two timestamps are equal when their `seconds` and `nanoseconds` are.
+ * Firestore addresses instants from the start of year 1 to the end of year
+ * 9999, and every constructor here checks for that range.
+ *
+ * @see {@link FirestoreSchema.Timestamp} for the schema of this value
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface Timestamp extends Equal.Equal, Inspectable.Inspectable {
+  readonly [TypeId]: typeof TypeId;
+  /** Seconds since the Unix epoch, negative before it. */
+  readonly seconds: number;
+  /** The fraction of that second, from 0 to 999,999,999. */
+  readonly nanoseconds: number;
+}
+/**
+ * Checks whether `u` is a {@link Timestamp} built by this module.
+ *
+ * An SDK's own `Timestamp` is not one.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export declare const isTimestamp: (u: unknown) => u is Timestamp;
+/**
+ * Builds a timestamp from seconds and nanoseconds, throwing on values
+ * Firestore cannot store.
+ *
+ * **When to use**
+ *
+ * Use for values known to be valid, such as constants. Use {@link make} for
+ * values you have not checked.
+ *
+ * **Details**
+ *
+ * Throws unless `seconds` is an integer from year 1 to year 9999, and
+ * `nanoseconds` is an integer from 0 to 999,999,999.
+ *
+ * @example Building a timestamp
+ * ```ts
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const epoch = Timestamp.makeUnsafe(0, 0);
+ * ```
+ *
+ * @see {@link make} for the same check returning an `Option`
+ * @see {@link fromMillisUnsafe} for building one from milliseconds
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const makeUnsafe: (seconds: number, nanoseconds: number) => Timestamp;
+/**
+ * Builds a timestamp from seconds and nanoseconds, or `None` for values
+ * Firestore cannot store.
+ *
+ * **When to use**
+ *
+ * Use when the fields come from outside the program, such as a request body,
+ * and may be invalid.
+ *
+ * **Details**
+ *
+ * Returns `None` unless `seconds` is an integer from year 1 to year 9999, and
+ * `nanoseconds` is an integer from 0 to 999,999,999.
+ *
+ * @example Building a timestamp from untrusted input
+ * ```ts
+ * import { Option } from "effect";
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const valid = Timestamp.make(1_700_000_000, 500); // Option.some(...)
+ * const invalid = Timestamp.make(0, -1); // Option.none()
+ *
+ * Option.isSome(valid); // true
+ * Option.isNone(invalid); // true
+ * ```
+ *
+ * @see {@link makeUnsafe} for the same check throwing instead
+ * @see {@link fromMillis} for building one from milliseconds
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const make: (seconds: number, nanoseconds: number) => Option.Option<Timestamp>;
+/**
+ * Builds a timestamp from milliseconds since the Unix epoch, throwing outside
+ * the range Firestore stores.
+ *
+ * **When to use**
+ *
+ * Use with millisecond values known to be in range, such as `Date.now()`.
+ *
+ * @example Building a timestamp from milliseconds
+ * ```ts
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const timestamp = Timestamp.fromMillisUnsafe(Date.now());
+ * ```
+ *
+ * @see {@link fromMillis} for the same check returning an `Option`
+ * @see {@link makeUnsafe} for building one from seconds and nanoseconds
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const fromMillisUnsafe: (millis: number) => Timestamp;
+/**
+ * Builds a timestamp from milliseconds since the Unix epoch, or `None` outside
+ * the range Firestore stores.
+ *
+ * **When to use**
+ *
+ * Use with millisecond values that may be out of range or not finite.
+ *
+ * @see {@link fromMillisUnsafe} for the same check throwing instead
+ * @see {@link toMillis} for the reverse conversion
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const fromMillis: (millis: number) => Option.Option<Timestamp>;
+/**
+ * Builds a timestamp from a `DateTime.Utc`, throwing outside the range
+ * Firestore stores.
+ *
+ * **When to use**
+ *
+ * Use with a `DateTime` known to fall between year 1 and year 9999, which
+ * covers almost every real date.
+ *
+ * **Details**
+ *
+ * A `DateTime.Utc` only carries milliseconds, so the result has no finer
+ * digits.
+ *
+ * @example Converting a DateTime
+ * ```ts
+ * import { DateTime } from "effect";
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const timestamp = Timestamp.fromDateTimeUnsafe(DateTime.makeUnsafe("2024-01-01T00:00:00Z"));
+ * ```
+ *
+ * @see {@link fromDateTime} for the same check returning an `Option`
+ * @see {@link toDateTime} for the reverse conversion
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const fromDateTimeUnsafe: (dateTime: DateTime.Utc) => Timestamp;
+/**
+ * Builds a timestamp from a `DateTime.Utc`, or `None` outside the range
+ * Firestore stores.
+ *
+ * **When to use**
+ *
+ * Use with a `DateTime` that may fall outside year 1 to year 9999, such as one
+ * parsed from user input.
+ *
+ * **Details**
+ *
+ * A `DateTime.Utc` only carries milliseconds, so the result has no finer
+ * digits.
+ *
+ * @see {@link fromDateTimeUnsafe} for the same check throwing instead
+ * @see {@link toDateTime} for the reverse conversion
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const fromDateTime: (dateTime: DateTime.Utc) => Option.Option<Timestamp>;
+/**
+ * The current instant, read from Effect's `Clock`, to the millisecond.
+ *
+ * **When to use**
+ *
+ * Use when the time this program sees is the one to store, and when a test
+ * should control it through `TestClock`.
+ *
+ * **Details**
+ *
+ * This is the local clock, not the database's. Clients with skewed clocks
+ * write different times for the same moment.
+ *
+ * @example Reading the current time
+ * ```ts
+ * import { Effect } from "effect";
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const program = Effect.gen(function* () {
+ *   const now = yield* Timestamp.now;
+ *   return Timestamp.toMillis(now);
+ * });
+ * ```
+ *
+ * @see {@link FieldValue.serverTimestamp} for the time the server applies the write
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const now: Effect.Effect<Timestamp>;
+/**
+ * Converts a timestamp to milliseconds since the Unix epoch, dropping the
+ * finer digits.
+ *
+ * @see {@link fromMillis} for the reverse conversion
+ * @see {@link toDateTime} for converting to a `DateTime.Utc`
+ *
+ * @stability unstable
+ * @category conversions
+ * @since 0.2.0
+ */
+export declare const toMillis: (self: Timestamp) => number;
+/**
+ * Converts a timestamp to a `DateTime.Utc`, dropping the digits finer than a
+ * millisecond.
+ *
+ * @see {@link fromDateTime} for the reverse conversion
+ * @see {@link toMillis} for converting to milliseconds
+ *
+ * @stability unstable
+ * @category conversions
+ * @since 0.2.0
+ */
+export declare const toDateTime: (self: Timestamp) => DateTime.Utc;
+/**
+ * Orders timestamps from earliest to latest, at full precision.
+ *
+ * @example Sorting timestamps
+ * ```ts
+ * import { Array } from "effect";
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const sorted = Array.sort(
+ *   [Timestamp.makeUnsafe(2, 0), Timestamp.makeUnsafe(1, 500)],
+ *   Timestamp.Order,
+ * );
+ * ```
+ *
+ * @stability unstable
+ * @category ordering
+ * @since 0.2.0
+ */
+export declare const Order: Order$1.Order<Timestamp>;
+export { Timestamp_d_exports };

package/dist/firestore/Timestamp.mjs

@@ -0,0 +1,255 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { Order as Order$1, fromDateTime as fromDateTime$1, fromDateTimeUnsafe as fromDateTimeUnsafe$1, fromMillis as fromMillis$1, fromMillisUnsafe as fromMillisUnsafe$1, isTimestamp as isTimestamp$1, make as make$1, makeUnsafe as makeUnsafe$1, now as now$1, toDateTime as toDateTime$1, toMillis as toMillis$1 } from "./internal/timestamp.mjs";
+// src/firestore/Timestamp.ts
+var Timestamp_exports = /* @__PURE__ */ __exportAll({
+	Order: () => Order,
+	fromDateTime: () => fromDateTime,
+	fromDateTimeUnsafe: () => fromDateTimeUnsafe,
+	fromMillis: () => fromMillis,
+	fromMillisUnsafe: () => fromMillisUnsafe,
+	isTimestamp: () => isTimestamp,
+	make: () => make,
+	makeUnsafe: () => makeUnsafe,
+	now: () => now,
+	toDateTime: () => toDateTime,
+	toMillis: () => toMillis
+});
+/**
+* Checks whether `u` is a {@link Timestamp} built by this module.
+*
+* An SDK's own `Timestamp` is not one.
+*
+* @stability unstable
+* @category guards
+* @since 0.2.0
+*/
+const isTimestamp = isTimestamp$1;
+/**
+* Builds a timestamp from seconds and nanoseconds, throwing on values
+* Firestore cannot store.
+*
+* **When to use**
+*
+* Use for values known to be valid, such as constants. Use {@link make} for
+* values you have not checked.
+*
+* **Details**
+*
+* Throws unless `seconds` is an integer from year 1 to year 9999, and
+* `nanoseconds` is an integer from 0 to 999,999,999.
+*
+* @example Building a timestamp
+* ```ts
+* import { Timestamp } from "@visiolab/effect-firebase/firestore";
+*
+* const epoch = Timestamp.makeUnsafe(0, 0);
+* ```
+*
+* @see {@link make} for the same check returning an `Option`
+* @see {@link fromMillisUnsafe} for building one from milliseconds
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const makeUnsafe = makeUnsafe$1;
+/**
+* Builds a timestamp from seconds and nanoseconds, or `None` for values
+* Firestore cannot store.
+*
+* **When to use**
+*
+* Use when the fields come from outside the program, such as a request body,
+* and may be invalid.
+*
+* **Details**
+*
+* Returns `None` unless `seconds` is an integer from year 1 to year 9999, and
+* `nanoseconds` is an integer from 0 to 999,999,999.
+*
+* @example Building a timestamp from untrusted input
+* ```ts
+* import { Option } from "effect";
+* import { Timestamp } from "@visiolab/effect-firebase/firestore";
+*
+* const valid = Timestamp.make(1_700_000_000, 500); // Option.some(...)
+* const invalid = Timestamp.make(0, -1); // Option.none()
+*
+* Option.isSome(valid); // true
+* Option.isNone(invalid); // true
+* ```
+*
+* @see {@link makeUnsafe} for the same check throwing instead
+* @see {@link fromMillis} for building one from milliseconds
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const make = make$1;
+/**
+* Builds a timestamp from milliseconds since the Unix epoch, throwing outside
+* the range Firestore stores.
+*
+* **When to use**
+*
+* Use with millisecond values known to be in range, such as `Date.now()`.
+*
+* @example Building a timestamp from milliseconds
+* ```ts
+* import { Timestamp } from "@visiolab/effect-firebase/firestore";
+*
+* const timestamp = Timestamp.fromMillisUnsafe(Date.now());
+* ```
+*
+* @see {@link fromMillis} for the same check returning an `Option`
+* @see {@link makeUnsafe} for building one from seconds and nanoseconds
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const fromMillisUnsafe = fromMillisUnsafe$1;
+/**
+* Builds a timestamp from milliseconds since the Unix epoch, or `None` outside
+* the range Firestore stores.
+*
+* **When to use**
+*
+* Use with millisecond values that may be out of range or not finite.
+*
+* @see {@link fromMillisUnsafe} for the same check throwing instead
+* @see {@link toMillis} for the reverse conversion
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const fromMillis = fromMillis$1;
+/**
+* Builds a timestamp from a `DateTime.Utc`, throwing outside the range
+* Firestore stores.
+*
+* **When to use**
+*
+* Use with a `DateTime` known to fall between year 1 and year 9999, which
+* covers almost every real date.
+*
+* **Details**
+*
+* A `DateTime.Utc` only carries milliseconds, so the result has no finer
+* digits.
+*
+* @example Converting a DateTime
+* ```ts
+* import { DateTime } from "effect";
+* import { Timestamp } from "@visiolab/effect-firebase/firestore";
+*
+* const timestamp = Timestamp.fromDateTimeUnsafe(DateTime.makeUnsafe("2024-01-01T00:00:00Z"));
+* ```
+*
+* @see {@link fromDateTime} for the same check returning an `Option`
+* @see {@link toDateTime} for the reverse conversion
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const fromDateTimeUnsafe = fromDateTimeUnsafe$1;
+/**
+* Builds a timestamp from a `DateTime.Utc`, or `None` outside the range
+* Firestore stores.
+*
+* **When to use**
+*
+* Use with a `DateTime` that may fall outside year 1 to year 9999, such as one
+* parsed from user input.
+*
+* **Details**
+*
+* A `DateTime.Utc` only carries milliseconds, so the result has no finer
+* digits.
+*
+* @see {@link fromDateTimeUnsafe} for the same check throwing instead
+* @see {@link toDateTime} for the reverse conversion
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const fromDateTime = fromDateTime$1;
+/**
+* The current instant, read from Effect's `Clock`, to the millisecond.
+*
+* **When to use**
+*
+* Use when the time this program sees is the one to store, and when a test
+* should control it through `TestClock`.
+*
+* **Details**
+*
+* This is the local clock, not the database's. Clients with skewed clocks
+* write different times for the same moment.
+*
+* @example Reading the current time
+* ```ts
+* import { Effect } from "effect";
+* import { Timestamp } from "@visiolab/effect-firebase/firestore";
+*
+* const program = Effect.gen(function* () {
+*   const now = yield* Timestamp.now;
+*   return Timestamp.toMillis(now);
+* });
+* ```
+*
+* @see {@link FieldValue.serverTimestamp} for the time the server applies the write
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const now = now$1;
+/**
+* Converts a timestamp to milliseconds since the Unix epoch, dropping the
+* finer digits.
+*
+* @see {@link fromMillis} for the reverse conversion
+* @see {@link toDateTime} for converting to a `DateTime.Utc`
+*
+* @stability unstable
+* @category conversions
+* @since 0.2.0
+*/
+const toMillis = toMillis$1;
+/**
+* Converts a timestamp to a `DateTime.Utc`, dropping the digits finer than a
+* millisecond.
+*
+* @see {@link fromDateTime} for the reverse conversion
+* @see {@link toMillis} for converting to milliseconds
+*
+* @stability unstable
+* @category conversions
+* @since 0.2.0
+*/
+const toDateTime = toDateTime$1;
+/**
+* Orders timestamps from earliest to latest, at full precision.
+*
+* @example Sorting timestamps
+* ```ts
+* import { Array } from "effect";
+* import { Timestamp } from "@visiolab/effect-firebase/firestore";
+*
+* const sorted = Array.sort(
+*   [Timestamp.makeUnsafe(2, 0), Timestamp.makeUnsafe(1, 500)],
+*   Timestamp.Order,
+* );
+* ```
+*
+* @stability unstable
+* @category ordering
+* @since 0.2.0
+*/
+const Order = Order$1;
+export { Order, Timestamp_exports, fromDateTime, fromDateTimeUnsafe, fromMillis, fromMillisUnsafe, isTimestamp, make, makeUnsafe, now, toDateTime, toMillis };

package/dist/firestore/index.d.mts

@@ -0,0 +1,14 @@
+import { DocumentSnapshot_d_exports } from "./DocumentSnapshot.mjs";
+import { DocumentPath_d_exports } from "./DocumentPath.mjs";
+import { FieldValue_d_exports } from "./FieldValue.mjs";
+import { GeoPoint_d_exports } from "./GeoPoint.mjs";
+import { Timestamp_d_exports } from "./Timestamp.mjs";
+import { FirestoreSchema_d_exports } from "./FirestoreSchema.mjs";
+import { Patch_d_exports } from "./Patch.mjs";
+import { FirestoreModel_d_exports } from "./FirestoreModel.mjs";
+import { Collection_d_exports } from "./Collection.mjs";
+import { FirestoreValue_d_exports } from "./FirestoreValue.mjs";
+import { QuerySnapshot_d_exports } from "./QuerySnapshot.mjs";
+import { Firestore_d_exports } from "./Firestore.mjs";
+import { CollectionGroup_d_exports } from "./CollectionGroup.mjs";
+export { Collection_d_exports as Collection, CollectionGroup_d_exports as CollectionGroup, DocumentPath_d_exports as DocumentPath, DocumentSnapshot_d_exports as DocumentSnapshot, FieldValue_d_exports as FieldValue, Firestore_d_exports as Firestore, FirestoreModel_d_exports as FirestoreModel, FirestoreSchema_d_exports as FirestoreSchema, FirestoreValue_d_exports as FirestoreValue, GeoPoint_d_exports as GeoPoint, Patch_d_exports as Patch, QuerySnapshot_d_exports as QuerySnapshot, Timestamp_d_exports as Timestamp };

package/dist/firestore/index.mjs

@@ -0,0 +1,14 @@
+import { Collection_exports } from "./Collection.mjs";
+import { CollectionGroup_exports } from "./CollectionGroup.mjs";
+import { DocumentPath_exports } from "./DocumentPath.mjs";
+import { DocumentSnapshot_exports } from "./DocumentSnapshot.mjs";
+import { FieldValue_exports } from "./FieldValue.mjs";
+import { Firestore_exports } from "./Firestore.mjs";
+import { FirestoreModel_exports } from "./FirestoreModel.mjs";
+import { FirestoreSchema_exports } from "./FirestoreSchema.mjs";
+import { FirestoreValue_exports } from "./FirestoreValue.mjs";
+import { GeoPoint_exports } from "./GeoPoint.mjs";
+import { Patch_exports } from "./Patch.mjs";
+import { QuerySnapshot_exports } from "./QuerySnapshot.mjs";
+import { Timestamp_exports } from "./Timestamp.mjs";
+export { Collection_exports as Collection, CollectionGroup_exports as CollectionGroup, DocumentPath_exports as DocumentPath, DocumentSnapshot_exports as DocumentSnapshot, FieldValue_exports as FieldValue, Firestore_exports as Firestore, FirestoreModel_exports as FirestoreModel, FirestoreSchema_exports as FirestoreSchema, FirestoreValue_exports as FirestoreValue, GeoPoint_exports as GeoPoint, Patch_exports as Patch, QuerySnapshot_exports as QuerySnapshot, Timestamp_exports as Timestamp };