pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/firestore/bytes.ts

@@ -0,0 +1,56 @@
+import { boundedActivityBytes, registerActivityValue } from './sandbox/activity-value-registry.js';
+import { registerQueryValue } from './sandbox/query-value-registry.js';
+
+export class Bytes {
+  private constructor(private readonly bytes: Uint8Array) {
+    registerActivityValue(this, boundedActivityBytes(bytes));
+    registerQueryValue(this, Object.freeze({
+      type: 'bytes',
+      values: Object.freeze(Array.from(bytes)),
+    }), () => new Bytes(bytes.slice()));
+  }
+
+  static fromBase64String(base64: string): Bytes {
+    const binary = atob(base64);
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    return new Bytes(bytes);
+  }
+
+  static fromUint8Array(array: Uint8Array): Bytes {
+    return new Bytes(array.slice());
+  }
+
+  toBase64(): string {
+    let binary = '';
+    for (const byte of this.bytes) binary += String.fromCharCode(byte);
+    return btoa(binary);
+  }
+
+  toUint8Array(): Uint8Array {
+    return this.bytes.slice();
+  }
+
+  toString(): string {
+    return `Bytes(base64: ${this.toBase64()})`;
+  }
+
+  isEqual(other: Bytes): boolean {
+    return other instanceof Bytes
+      && this.bytes.length === other.bytes.length
+      && this.bytes.every((byte, index) => byte === other.bytes[index]);
+  }
+
+  toJSON(): object {
+    return { type: 'firestore/bytes/1.0', bytes: this.toBase64() };
+  }
+
+  static fromJSON(json: object): Bytes {
+    const value = json as { readonly type?: unknown; readonly bytes?: unknown };
+    const hasUnexpectedMarker = value.type !== 'firestore/bytes/1.0';
+    const isInvalidBytesJson = hasUnexpectedMarker || typeof value.bytes !== 'string';
+    if (isInvalidBytesJson) {
+      throw new TypeError('Invalid Bytes JSON value.');
+    }
+    return Bytes.fromBase64String(value.bytes);
+  }
+}

package/src/firestore/converter-method.ts

@@ -0,0 +1,49 @@
+/**
+ * `pyric/firestore` — the `withConverter` instance method for collection and
+ * query values.
+ *
+ * Document references get theirs from `registerDocumentValue` in `refs.ts`,
+ * which builds a fresh shell per view. Collections and queries are the
+ * chainable sandbox value itself (or a converter shell over one), so the
+ * method is attached to every value `collection` / `collectionGroup` /
+ * `query` hands back, and to each shell those produce.
+ *
+ * Package-internal: not re-exported by the barrel, so it stays off the
+ * published `pyric/firestore` surface.
+ */
+import {
+  targetOf,
+  underlyingOf,
+  buildSandboxShell,
+} from './state.js';
+import { copyQueryValueRegistration } from './sandbox/query-value-registry.js';
+import type { DocumentData, FirestoreDataConverter } from './types.js';
+
+/**
+ * A fresh typed view over a collection or query. `null` strips the converter
+ * and hands back the underlying untyped value, which already carries the
+ * method. Documents are not routed here — `withConverter` in `refs.ts` keeps
+ * its own document branch.
+ */
+export function convertedView(
+  source: object,
+  converter: FirestoreDataConverter<unknown, DocumentData> | null,
+): object {
+  const underlying = underlyingOf(source);
+  const removesConverter = converter === null;
+  if (removesConverter) return underlying;
+  const target = targetOf(source);
+  const shell = buildSandboxShell(underlying as { id?: string; path?: string }, target, converter);
+  copyQueryValueRegistration(underlying, shell);
+  return attachConverterMethod(shell);
+}
+
+/** Attach Firebase's `withConverter` method to a collection or query value. */
+export function attachConverterMethod<V extends object>(value: V): V {
+  function convert<A, D extends DocumentData = DocumentData>(converter: FirestoreDataConverter<A, D>): V;
+  function convert(converter: null): V;
+  function convert(converter: FirestoreDataConverter<unknown, DocumentData> | null): object {
+    return convertedView(value, converter);
+  }
+  return Object.assign(value, { withConverter: convert });
+}

package/src/firestore/errors.ts

@@ -4,6 +4,11 @@ interface CodedError extends Error {
   code: string;
   denialContext?: unknown;
   remediation?: unknown;
+  request?: unknown;
+  resource?: unknown;
+  query?: unknown;
+  rule?: unknown;
+  queryProof?: unknown;
 }
 
 function isCodedError(error: unknown): error is CodedError {
@@ -33,6 +38,9 @@ export function toFirestoreFirebaseError(error: unknown): unknown {
   if (error.remediation !== undefined) {
     Object.assign(translated, { remediation: error.remediation });
   }
+  for (const field of ['request', 'resource', 'query', 'rule', 'queryProof'] as const) {
+    if (error[field] !== undefined) Object.assign(translated, { [field]: error[field] });
+  }
   return translated;
 }
 

package/src/firestore/field-values.ts

@@ -10,117 +10,10 @@ import {
   Timestamp as ChainTimestamp,
   type FieldValueSentinel,
 } from 'pyric/sandbox/admin-firestore';
-import {
-  boundedActivityBytes,
-  boundedActivityIdentity,
-  registerActivityValue,
-} from './sandbox/activity-value-registry.js';
-import { registerQueryValue } from './sandbox/query-value-registry.js';
-
-export class Bytes {
-  private constructor(private readonly bytes: Uint8Array) {
-    registerActivityValue(this, boundedActivityBytes(bytes));
-    registerQueryValue(this, Object.freeze({
-      type: 'bytes',
-      values: Object.freeze(Array.from(bytes)),
-    }), () => new Bytes(bytes.slice()));
-  }
-
-  static fromBase64String(base64: string): Bytes {
-    const binary = atob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
-    return new Bytes(bytes);
-  }
-
-  static fromUint8Array(array: Uint8Array): Bytes {
-    return new Bytes(array.slice());
-  }
-
-  toBase64(): string {
-    let binary = '';
-    for (const byte of this.bytes) binary += String.fromCharCode(byte);
-    return btoa(binary);
-  }
-
-  toUint8Array(): Uint8Array {
-    return this.bytes.slice();
-  }
-
-  toString(): string {
-    return `Bytes(base64: ${this.toBase64()})`;
-  }
-
-  isEqual(other: Bytes): boolean {
-    return other instanceof Bytes
-      && this.bytes.length === other.bytes.length
-      && this.bytes.every((byte, index) => byte === other.bytes[index]);
-  }
-
-  toJSON(): object {
-    return { type: 'firestore/bytes/1.0', bytes: this.toBase64() };
-  }
-
-  static fromJSON(json: object): Bytes {
-    const value = json as { type?: unknown; bytes?: unknown };
-    if (value.type !== 'firestore/bytes/1.0' || typeof value.bytes !== 'string') {
-      throw new TypeError('Invalid Bytes JSON value.');
-    }
-    return Bytes.fromBase64String(value.bytes);
-  }
-}
-
-export class GeoPoint {
-  constructor(
-    private readonly lat: number,
-    private readonly lng: number,
-  ) {
-    if (!Number.isFinite(lat) || lat < -90 || lat > 90) {
-      throw new TypeError('Latitude must be a number between -90 and 90.');
-    }
-    if (!Number.isFinite(lng) || lng < -180 || lng > 180) {
-      throw new TypeError('Longitude must be a number between -180 and 180.');
-    }
-    registerActivityValue(
-      this,
-      boundedActivityIdentity('geo-point', String(lat), '\0', String(lng)),
-    );
-    registerQueryValue(this, Object.freeze({
-      type: 'geo-point',
-      latitude: lat,
-      longitude: lng,
-    }), () => new GeoPoint(lat, lng));
-  }
 
-  get latitude(): number { return this.lat; }
-  get longitude(): number { return this.lng; }
+export { Bytes } from './bytes.js';
 
-  isEqual(other: GeoPoint): boolean {
-    return other instanceof GeoPoint
-      && this.lat === other.lat
-      && this.lng === other.lng;
-  }
-
-  toJSON(): { latitude: number; longitude: number; type: string } {
-    return {
-      latitude: this.lat,
-      longitude: this.lng,
-      type: 'firestore/geoPoint/1.0',
-    };
-  }
-
-  static fromJSON(json: object): GeoPoint {
-    const value = json as { type?: unknown; latitude?: unknown; longitude?: unknown };
-    if (
-      value.type !== 'firestore/geoPoint/1.0'
-      || typeof value.latitude !== 'number'
-      || typeof value.longitude !== 'number'
-    ) {
-      throw new TypeError('Invalid GeoPoint JSON value.');
-    }
-    return new GeoPoint(value.latitude, value.longitude);
-  }
-}
+export { GeoPoint } from './geo-point.js';
 
 export class FieldPath {
   readonly _internalPath: { segments: string[]; offset: number; len: number };
@@ -149,55 +42,7 @@ export function documentId(): FieldPath {
   return new FieldPath('__name__');
 }
 
-export class VectorValue {
-  private constructor(readonly _values: number[]) {
-    registerQueryValue(this, Object.freeze({
-      type: 'vector',
-      values: Object.freeze(_values.slice()),
-    }), () => new VectorValue(_values.slice()));
-  }
-
-  static create(values: number[]): VectorValue {
-    if (!values.every((value) => typeof value === 'number')) {
-      throw new TypeError('Vector values must be numbers.');
-    }
-    return new VectorValue(values.slice());
-  }
-
-  toArray(): number[] {
-    return this._values.slice();
-  }
-
-  isEqual(other: VectorValue): boolean {
-    const theirs = other instanceof VectorValue ? other._values : undefined;
-    return theirs !== undefined
-      && this._values.length === theirs.length
-      && this._values.every((value, index) => value === theirs[index]);
-  }
-
-  toJSON(): object {
-    return {
-      type: 'firestore/vectorValue/1.0',
-      vectorValues: this.toArray(),
-    };
-  }
-
-  static fromJSON(json: object): VectorValue {
-    const value = json as { type?: unknown; vectorValues?: unknown };
-    if (
-      value.type !== 'firestore/vectorValue/1.0'
-      || !Array.isArray(value.vectorValues)
-      || !value.vectorValues.every((entry) => typeof entry === 'number')
-    ) {
-      throw new TypeError('Invalid VectorValue JSON value.');
-    }
-    return VectorValue.create(value.vectorValues);
-  }
-}
-
-export function vector(values: number[] = []): VectorValue {
-  return VectorValue.create(values);
-}
+export { VectorValue, vector } from './vector-value.js';
 
 export { ChainFieldValue as FieldValue, ChainTimestamp as Timestamp };
 

package/src/firestore/geo-point.ts

@@ -0,0 +1,56 @@
+import { boundedActivityIdentity, registerActivityValue } from './sandbox/activity-value-registry.js';
+import { registerQueryValue } from './sandbox/query-value-registry.js';
+
+export class GeoPoint {
+  constructor(
+    private readonly lat: number,
+    private readonly lng: number,
+  ) {
+    const isInvalidLatitude = !Number.isFinite(lat) || lat < -90 || lat > 90;
+    if (isInvalidLatitude) {
+      throw new TypeError('Latitude must be a number between -90 and 90.');
+    }
+    const isInvalidLongitude = !Number.isFinite(lng) || lng < -180 || lng > 180;
+    if (isInvalidLongitude) {
+      throw new TypeError('Longitude must be a number between -180 and 180.');
+    }
+    registerActivityValue(
+      this,
+      boundedActivityIdentity('geo-point', String(lat), '\0', String(lng)),
+    );
+    registerQueryValue(this, Object.freeze({
+      type: 'geo-point',
+      latitude: lat,
+      longitude: lng,
+    }), () => new GeoPoint(lat, lng));
+  }
+
+  get latitude(): number { return this.lat; }
+  get longitude(): number { return this.lng; }
+
+  isEqual(other: GeoPoint): boolean {
+    return other instanceof GeoPoint
+      && this.lat === other.lat
+      && this.lng === other.lng;
+  }
+
+  toJSON(): { latitude: number; longitude: number; type: string } {
+    return {
+      latitude: this.lat,
+      longitude: this.lng,
+      type: 'firestore/geoPoint/1.0',
+    };
+  }
+
+  static fromJSON(json: object): GeoPoint {
+    const value = json as { readonly type?: unknown; readonly latitude?: unknown; readonly longitude?: unknown };
+    const hasUnexpectedMarker = value.type !== 'firestore/geoPoint/1.0';
+    const isInvalidGeoPointJson = hasUnexpectedMarker
+      || typeof value.latitude !== 'number'
+      || typeof value.longitude !== 'number';
+    if (isInvalidGeoPointJson) {
+      throw new TypeError('Invalid GeoPoint JSON value.');
+    }
+    return new GeoPoint(value.latitude, value.longitude);
+  }
+}

package/src/firestore/index.ts

@@ -43,7 +43,7 @@ export * from './instances.js';
 export * from './equality.js';
 export * from './persistence.js';
 export * from './refs.js';
-export * from './reads.js';
+export { getDoc, getDocs } from './reads.js';
 export * from './writes.js';
 export * from './query-constraints.js';
 export * from './aggregates.js';

package/src/firestore/instances.ts

@@ -20,6 +20,7 @@ import {
   defaultClientApp,
   resolveClientApp,
 } from '../sandbox/internal/client-app.js';
+import { getAuthLens, onAuthLensChanged } from '../auth/modular.js';
 
 import {
   TARGET_SYMBOL,
@@ -84,9 +85,18 @@ export function getFirestore(target?: SandboxContext | Sandbox | FirebaseApp): F
         lifecycle.own(session.onCurrentUserChanged((user) => {
           getInternalEnv(sandbox).reevaluateLiveListeners(user, authScope);
         }));
+        lifecycle.own(onAuthLensChanged((lens) => {
+          const effectiveUser = lens?.mode === 'anon'
+            ? null
+            : lens?.mode === 'as'
+              ? { uid: lens.uid, ...(lens.tenant ? { tenant: lens.tenant } : {}) }
+              : session.currentUser;
+          getInternalEnv(sandbox).reevaluateLiveListeners(effectiveUser, authScope);
+        }));
       }
       const t: SandboxLiveTarget = {
         kind: 'sandbox-live',
+        activityApp: target as object,
         sandbox,
         getDb: makeGetDb(sandbox, () => session.currentUser),
         authScope,
@@ -99,6 +109,7 @@ export function getFirestore(target?: SandboxContext | Sandbox | FirebaseApp): F
     const chainable = getChainableFirestore(target);
     const t: SandboxTarget = {
       kind: 'sandbox',
+      activityApp: target,
       db: chainable,
       sandbox: target.sandbox,
       ...createFirestoreTargetLifecycle(),
@@ -108,6 +119,7 @@ export function getFirestore(target?: SandboxContext | Sandbox | FirebaseApp): F
   if (isSandbox(target)) {
     const t: SandboxLiveTarget = {
       kind: 'sandbox-live',
+      activityApp: target,
       sandbox: target,
       getDb: makeGetDb(target),
       ...createFirestoreTargetLifecycle(),
@@ -285,9 +297,18 @@ function makeGetDb(
   currentUser: () => AuthState = () => sandbox.currentUser,
 ): () => SandboxFirestore {
   return () => {
-    const ctx = bindOperationContext(sandbox.withAuth(currentUser()), {
+    const lens = getAuthLens();
+    if (lens?.mode === 'admin') {
+      return getChainableAdminFirestore(sandbox);
+    }
+    const effectiveAuth: AuthState = lens?.mode === 'anon'
+      ? null
+      : lens?.mode === 'as'
+        ? { uid: lens.uid, ...(lens.tenant ? { tenant: lens.tenant } : {}) }
+        : currentUser();
+    const ctx = bindOperationContext(sandbox.withAuth(effectiveAuth), {
       source: { kind: 'app' },
-      authLens: { mode: 'app-session' },
+      authLens: lens ?? { mode: 'app-session' },
     });
     return getChainableFirestore(ctx);
   };

package/src/firestore/internal/document-data.ts

@@ -0,0 +1,9 @@
+import { FirebaseError } from '../../sandbox/internal/firebase-error.js';
+import { isPlainObject } from '../plain-object.js';
+
+/** Reject invalid document roots before an adapter captures or queues a write. */
+export function requireDocumentData(value: unknown): Record<string, unknown> {
+  const isDocumentData = isPlainObject(value);
+  if (isDocumentData) return value;
+  throw new FirebaseError('invalid-argument', 'Document data must be a plain object.');
+}

package/src/firestore/internal/index.ts

@@ -12,3 +12,10 @@ export type {
   ActivityReport,
   ActivitySourceAttribution,
 } from '../sandbox/activity-monitor.js';
+
+// Diagnostic projections do not invoke arbitrary query-operand getters.
+export { activityValue } from '../sandbox/activity-query-value.js';
+export { activityStructuralIdentity } from '../sandbox/activity-structural-identity.js';
+
+// Served aliases preserve their existing backend path and public observation name.
+export { readDocumentAs, readQueryAs } from '../reads.js';