pyric 0.0.1 → 0.1.0-alpha.7

package/dist/storage/persistence.d.ts

@@ -0,0 +1,134 @@
+/**
+ * IndexedDB persistence layer for `pyric/storage`.
+ *
+ * One database (`pyric-storage` by default), two object stores —
+ * `blobs` for the file content and `metadata` for the descriptive
+ * record. Both stores key on the file's full path string. Object
+ * upload writes both stores within a single `readwrite` transaction
+ * so the pair stays consistent — a partial failure can't leave a
+ * blob without metadata or vice versa.
+ *
+ * Slice 3 of the v1 scope (per the design rationale):
+ *
+ * - Internal infrastructure; no public Storage API is exposed yet.
+ *   Slice 5 builds `getStorage` / `ref` / `uploadBytes` / `getBytes` on
+ *   top of this layer.
+ * - The `StoredMetadata` shape mirrors Firebase's `FullMetadata`
+ *   minus the `ref` field (computed at consumption time) and
+ *   `downloadTokens` (deferred — no browser-renderable URLs in the
+ *   v1 scope, per Section 4 of the survey).
+ * - Database name is overridable so tests can isolate state per
+ *   case via fake-indexeddb without colliding on the production
+ *   default `pyric-storage`.
+ *
+ * Errors raised from this module are raw `DOMException`-shaped
+ * objects — translation into Firebase-shaped `StorageError`s happens
+ * in Slice 8 inside `errors.ts`. Keep this layer mechanical.
+ */
+/**
+ * Persisted metadata for a single stored object. Mirrors Firebase's
+ * `FullMetadata` so Slice 6 (the public `getMetadata` /
+ * `updateMetadata` surface) can return this shape directly.
+ *
+ * Server-set fields (`generation`, `metageneration`, `timeCreated`,
+ * `updated`, `bucket`, `fullPath`, `name`, `size`) are populated by
+ * the upload pipeline before reaching this layer. The client-settable
+ * fields (`contentType` through `customMetadata`) flow in from the
+ * caller's `SettableMetadata`.
+ */
+export interface StoredMetadata {
+    /** Full path of the object within the bucket. Also the store key. */
+    fullPath: string;
+    /** Last path segment (`b.txt` in `a/b.txt`). */
+    name: string;
+    /** Sandbox bucket id. v1 has a single implicit bucket. */
+    bucket: string;
+    /** Monotonically increasing version of the object content. */
+    generation: string;
+    /** Monotonically increasing version of just the metadata. */
+    metageneration: string;
+    /** ISO-8601 timestamp of original creation. */
+    timeCreated: string;
+    /** ISO-8601 timestamp of the most recent update (content or metadata). */
+    updated: string;
+    /** Size of the blob in bytes. */
+    size: number;
+    /** Client-settable: MIME type. Defaults to `application/octet-stream`. */
+    contentType?: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    /** Free-form key/value annotations the client attached at upload. */
+    customMetadata?: Record<string, string>;
+    /** Hex-encoded MD5 hash of the content. Populated when computable. */
+    md5Hash?: string;
+}
+/**
+ * Persistence-layer interface. Higher layers (Slice 4's
+ * `StorageService`, Slice 5's reference operations) interact with
+ * the backend through this surface only — the IndexedDB calls stay
+ * isolated behind it.
+ *
+ * All methods are async and return a promise that settles when the
+ * underlying IDB transaction completes. Missing keys resolve to
+ * `undefined` rather than throwing; the public API translates that
+ * to `storage/object-not-found` in Slice 8.
+ */
+export interface StorageBackend {
+    /**
+     * Write a blob + its metadata atomically. Both stores update under
+     * one `readwrite` transaction so a failure on either path rolls
+     * the other back. Existing entries at the same path are replaced.
+     */
+    put(path: string, blob: Blob, metadata: StoredMetadata): Promise<void>;
+    /**
+     * Read the blob stored at `path`. Resolves to `undefined` when no
+     * entry exists — callers translate that into `object-not-found`.
+     */
+    getBlob(path: string): Promise<Blob | undefined>;
+    /**
+     * Read the metadata record stored at `path`. Resolves to
+     * `undefined` when no entry exists.
+     */
+    getMetadata(path: string): Promise<StoredMetadata | undefined>;
+    /**
+     * Replace the metadata record at `path` without touching the blob.
+     * Used by `updateMetadata` (Slice 6). Caller is responsible for
+     * preserving server-set fields (`generation`, `timeCreated`, …)
+     * the spec says metadata-only updates leave intact.
+     */
+    putMetadata(path: string, metadata: StoredMetadata): Promise<void>;
+    /**
+     * Delete both the blob and the metadata at `path` atomically.
+     * No-op when neither entry exists.
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * Enumerate metadata records whose `fullPath` starts with `prefix`.
+     * Returned in IndexedDB key order (lexicographic by path). The
+     * prefix is used verbatim — no implicit trailing-slash addition,
+     * matching the survey's path-semantics call (Section 6).
+     */
+    listByPrefix(prefix: string): Promise<StoredMetadata[]>;
+    /**
+     * Clear both stores. Called by Slice 4's `StorageService.reset`.
+     */
+    reset(): Promise<void>;
+    /**
+     * Close the underlying IndexedDB connection. Idempotent.
+     */
+    close(): void;
+}
+/**
+ * Open (or create) the backing database and return a backend bound
+ * to it. The connection stays open for the lifetime of the returned
+ * backend; call `close()` before discarding it so future opens get a
+ * clean handle.
+ *
+ * `dbName` is overridable so tests can isolate per-case state. In
+ * production, callers pass nothing and inherit the default
+ * `pyric-storage`.
+ */
+export declare function openStorageBackend(dbName?: string): Promise<StorageBackend>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/storage/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/storage/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAaH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAEjD;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAE/D;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAExD;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,GAAE,MAAwB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAEzB"}

package/dist/storage/persistence.js

@@ -0,0 +1,132 @@
+/**
+ * IndexedDB persistence layer for `pyric/storage`.
+ *
+ * One database (`pyric-storage` by default), two object stores —
+ * `blobs` for the file content and `metadata` for the descriptive
+ * record. Both stores key on the file's full path string. Object
+ * upload writes both stores within a single `readwrite` transaction
+ * so the pair stays consistent — a partial failure can't leave a
+ * blob without metadata or vice versa.
+ *
+ * Slice 3 of the v1 scope (per the design rationale):
+ *
+ * - Internal infrastructure; no public Storage API is exposed yet.
+ *   Slice 5 builds `getStorage` / `ref` / `uploadBytes` / `getBytes` on
+ *   top of this layer.
+ * - The `StoredMetadata` shape mirrors Firebase's `FullMetadata`
+ *   minus the `ref` field (computed at consumption time) and
+ *   `downloadTokens` (deferred — no browser-renderable URLs in the
+ *   v1 scope, per Section 4 of the survey).
+ * - Database name is overridable so tests can isolate state per
+ *   case via fake-indexeddb without colliding on the production
+ *   default `pyric-storage`.
+ *
+ * Errors raised from this module are raw `DOMException`-shaped
+ * objects — translation into Firebase-shaped `StorageError`s happens
+ * in Slice 8 inside `errors.ts`. Keep this layer mechanical.
+ */
+const DEFAULT_DB_NAME = 'pyric-storage';
+/**
+ * Schema version. Bump and add an `upgradeneeded` branch when the
+ * store layout changes. Slice 3 ships v1: two object stores keyed by
+ * fullPath, no indexes. Future migrations follow IndexedDB's standard
+ * upgrade path.
+ */
+const SCHEMA_VERSION = 1;
+const BLOBS_STORE = 'blobs';
+const METADATA_STORE = 'metadata';
+/**
+ * Open (or create) the backing database and return a backend bound
+ * to it. The connection stays open for the lifetime of the returned
+ * backend; call `close()` before discarding it so future opens get a
+ * clean handle.
+ *
+ * `dbName` is overridable so tests can isolate per-case state. In
+ * production, callers pass nothing and inherit the default
+ * `pyric-storage`.
+ */
+export function openStorageBackend(dbName = DEFAULT_DB_NAME) {
+    return openDatabase(dbName).then((db) => new IndexedDbStorageBackend(db));
+}
+// ─── Internal ──────────────────────────────────────────────────────
+class IndexedDbStorageBackend {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async put(path, blob, metadata) {
+        const tx = this.db.transaction([BLOBS_STORE, METADATA_STORE], 'readwrite');
+        tx.objectStore(BLOBS_STORE).put(blob, path);
+        tx.objectStore(METADATA_STORE).put(metadata, path);
+        await awaitTransaction(tx);
+    }
+    async getBlob(path) {
+        const tx = this.db.transaction(BLOBS_STORE, 'readonly');
+        return awaitRequest(tx.objectStore(BLOBS_STORE).get(path));
+    }
+    async getMetadata(path) {
+        const tx = this.db.transaction(METADATA_STORE, 'readonly');
+        return awaitRequest(tx.objectStore(METADATA_STORE).get(path));
+    }
+    async putMetadata(path, metadata) {
+        const tx = this.db.transaction(METADATA_STORE, 'readwrite');
+        tx.objectStore(METADATA_STORE).put(metadata, path);
+        await awaitTransaction(tx);
+    }
+    async delete(path) {
+        const tx = this.db.transaction([BLOBS_STORE, METADATA_STORE], 'readwrite');
+        tx.objectStore(BLOBS_STORE).delete(path);
+        tx.objectStore(METADATA_STORE).delete(path);
+        await awaitTransaction(tx);
+    }
+    async listByPrefix(prefix) {
+        const tx = this.db.transaction(METADATA_STORE, 'readonly');
+        // `IDBKeyRange.bound(prefix, prefix + '￿')` returns every
+        // key that starts with `prefix` — '￿' is the highest BMP
+        // code point, so any path whose first char beyond `prefix` is
+        // legal will sort below it. Matches the survey's recommended
+        // prefix-query pattern (Section 6).
+        const range = IDBKeyRange.bound(prefix, prefix + '￿', false, false);
+        return awaitRequest(tx.objectStore(METADATA_STORE).getAll(range));
+    }
+    async reset() {
+        const tx = this.db.transaction([BLOBS_STORE, METADATA_STORE], 'readwrite');
+        tx.objectStore(BLOBS_STORE).clear();
+        tx.objectStore(METADATA_STORE).clear();
+        await awaitTransaction(tx);
+    }
+    close() {
+        this.db.close();
+    }
+}
+function openDatabase(dbName) {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.open(dbName, SCHEMA_VERSION);
+        req.addEventListener('upgradeneeded', () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(BLOBS_STORE)) {
+                db.createObjectStore(BLOBS_STORE);
+            }
+            if (!db.objectStoreNames.contains(METADATA_STORE)) {
+                db.createObjectStore(METADATA_STORE);
+            }
+        });
+        req.addEventListener('success', () => resolve(req.result));
+        req.addEventListener('error', () => reject(req.error));
+        req.addEventListener('blocked', () => reject(new Error(`IndexedDB open blocked for db "${dbName}"`)));
+    });
+}
+function awaitRequest(req) {
+    return new Promise((resolve, reject) => {
+        req.addEventListener('success', () => resolve(req.result));
+        req.addEventListener('error', () => reject(req.error));
+    });
+}
+function awaitTransaction(tx) {
+    return new Promise((resolve, reject) => {
+        tx.addEventListener('complete', () => resolve());
+        tx.addEventListener('error', () => reject(tx.error));
+        tx.addEventListener('abort', () => reject(tx.error ?? new Error('IndexedDB transaction aborted')));
+    });
+}
+//# sourceMappingURL=persistence.js.map

package/dist/storage/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/storage/persistence.ts"],"names":[],"mappings":"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"}

package/dist/storage/reference.d.ts

@@ -0,0 +1,63 @@
+/**
+ * StorageReference + `ref()` factory.
+ *
+ * Mirrors the public shape `firebase/storage` exposes: `fullPath`,
+ * `bucket`, `name`, `parent`, `root`, `storage`, plus `toString()`
+ * returning `gs://<bucket>/<fullPath>`.
+ *
+ * Two ref impls — sandbox (carries path + storage, computes the
+ * other fields) and prod (proxies to an underlying
+ * `firebase/storage` ref via a WeakMap). Both implement the same
+ * `StorageReference` shape so consumer code is target-blind.
+ *
+ * Identity model: references are value objects. Two refs with the
+ * same `(storage, fullPath)` compare equal via `toString()` /
+ * `fullPath`, NOT via `===` — Firebase doesn't intern references
+ * either, and consumer code that relies on identity for caching is
+ * outside the contract.
+ *
+ * Path normalization matches Firebase exactly: leading slashes
+ * stripped, trailing slashes stripped, repeated internal slashes
+ * collapsed. Empty path is legal — it's the root reference.
+ */
+import * as fb from 'firebase/storage';
+import { type FirebaseStorage } from './service.js';
+/**
+ * Public reference shape. Methods are inherited from the impl
+ * classes below; the interface is exported so consumer code can
+ * name the type without depending on the impls.
+ */
+export interface StorageReference {
+    readonly storage: FirebaseStorage;
+    readonly bucket: string;
+    readonly fullPath: string;
+    readonly name: string;
+    readonly parent: StorageReference | null;
+    readonly root: StorageReference;
+    toString(): string;
+}
+/** Internal — extract the underlying `fb.StorageReference` for a prod ref. */
+export declare function fbRefOf(ref: StorageReference): fb.StorageReference;
+/**
+ * Construct a reference. Two overloads matching Firebase:
+ *
+ *   `ref(storage, path?)`   — `path` is bucket-rooted. Omit for root.
+ *   `ref(parent, path)`     — `path` is relative to `parent.fullPath`.
+ */
+export declare function ref(storage: FirebaseStorage, path?: string): StorageReference;
+export declare function ref(parent: StorageReference, path: string): StorageReference;
+/**
+ * Normalize a single path: strip leading/trailing slashes, collapse
+ * repeated internal slashes. Empty stays empty (the root).
+ *
+ * Matches Firebase's behavior — relevant when consumer code passes
+ * `/sessions/s1.json` or `sessions//s1.json`; both end up at
+ * `sessions/s1.json`.
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * Join a parent path with a child path, normalizing the result.
+ * Used by the `ref(parent, path)` overload and by `child` helpers.
+ */
+export declare function joinPaths(parent: string, child: string): string;
+//# sourceMappingURL=reference.d.ts.map

package/dist/storage/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../src/storage/reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,IAAI,MAAM,CAAC;CACpB;AASD,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,EAAE,CAAC,gBAAgB,CASlE;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;AAC/E,wBAAgB,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;AAyF9E;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/D"}

package/dist/storage/reference.js

@@ -0,0 +1,156 @@
+/**
+ * StorageReference + `ref()` factory.
+ *
+ * Mirrors the public shape `firebase/storage` exposes: `fullPath`,
+ * `bucket`, `name`, `parent`, `root`, `storage`, plus `toString()`
+ * returning `gs://<bucket>/<fullPath>`.
+ *
+ * Two ref impls — sandbox (carries path + storage, computes the
+ * other fields) and prod (proxies to an underlying
+ * `firebase/storage` ref via a WeakMap). Both implement the same
+ * `StorageReference` shape so consumer code is target-blind.
+ *
+ * Identity model: references are value objects. Two refs with the
+ * same `(storage, fullPath)` compare equal via `toString()` /
+ * `fullPath`, NOT via `===` — Firebase doesn't intern references
+ * either, and consumer code that relies on identity for caching is
+ * outside the contract.
+ *
+ * Path normalization matches Firebase exactly: leading slashes
+ * stripped, trailing slashes stripped, repeated internal slashes
+ * collapsed. Empty path is legal — it's the root reference.
+ */
+import * as fb from 'firebase/storage';
+import { TARGET_SYMBOL, targetOf } from './service.js';
+/**
+ * Internal — map from prod-target StorageReferences to their backing
+ * `firebase/storage` references. Ops use this to delegate. WeakMap
+ * keys let entries GC alongside the refs that produced them.
+ */
+const PROD_FB_REF = new WeakMap();
+/** Internal — extract the underlying `fb.StorageReference` for a prod ref. */
+export function fbRefOf(ref) {
+    const r = PROD_FB_REF.get(ref);
+    if (!r) {
+        throw new Error('pyric/storage: expected a prod-target reference but the WeakMap had no entry. ' +
+            'Mixing sandbox + prod refs in the same call?');
+    }
+    return r;
+}
+export function ref(target, path) {
+    if (isStorageReference(target)) {
+        // Relative-to-parent overload.
+        const parentTarget = targetOf(target.storage);
+        if (parentTarget.kind === 'prod') {
+            const newFbRef = fb.ref(fbRefOf(target), path ?? '');
+            return wrapProdRef(target.storage, newFbRef);
+        }
+        return new SandboxStorageReference(target.storage, joinPaths(target.fullPath, path ?? ''));
+    }
+    // Storage-rooted overload.
+    const t = targetOf(target);
+    if (t.kind === 'prod') {
+        const fbR = path === undefined ? fb.ref(t.fbStorage) : fb.ref(t.fbStorage, path);
+        return wrapProdRef(target, fbR);
+    }
+    return new SandboxStorageReference(target, normalizePath(path ?? ''));
+}
+// ─── Sandbox impl ──────────────────────────────────────────────────
+class SandboxStorageReference {
+    storage;
+    bucket;
+    fullPath;
+    constructor(storage, fullPath) {
+        this.storage = storage;
+        // Sandbox handles always have a sandbox target; pull bucket from it.
+        const t = targetOf(storage);
+        this.bucket = t.bucket;
+        this.fullPath = fullPath;
+    }
+    get name() {
+        if (this.fullPath === '')
+            return '';
+        const idx = this.fullPath.lastIndexOf('/');
+        return idx === -1 ? this.fullPath : this.fullPath.slice(idx + 1);
+    }
+    get parent() {
+        if (this.fullPath === '')
+            return null;
+        const idx = this.fullPath.lastIndexOf('/');
+        const parentPath = idx === -1 ? '' : this.fullPath.slice(0, idx);
+        return new SandboxStorageReference(this.storage, parentPath);
+    }
+    get root() {
+        if (this.fullPath === '')
+            return this;
+        return new SandboxStorageReference(this.storage, '');
+    }
+    toString() {
+        return `gs://${this.bucket}/${this.fullPath}`;
+    }
+}
+// ─── Prod impl ─────────────────────────────────────────────────────
+/**
+ * Wrap a `firebase/storage` ref in our `StorageReference` shape.
+ * Tags it in `PROD_FB_REF` so ops can recover the underlying ref.
+ * `parent` / `root` recursively wrap to keep the target consistent.
+ */
+function wrapProdRef(storage, fbR) {
+    const wrapper = {
+        storage,
+        get bucket() { return fbR.bucket; },
+        get fullPath() { return fbR.fullPath; },
+        get name() { return fbR.name; },
+        get parent() {
+            const p = fbR.parent;
+            return p ? wrapProdRef(storage, p) : null;
+        },
+        get root() {
+            return wrapProdRef(storage, fbR.root);
+        },
+        toString() { return fbR.toString(); },
+    };
+    PROD_FB_REF.set(wrapper, fbR);
+    return wrapper;
+}
+// ─── Path utilities ────────────────────────────────────────────────
+/**
+ * Normalize a single path: strip leading/trailing slashes, collapse
+ * repeated internal slashes. Empty stays empty (the root).
+ *
+ * Matches Firebase's behavior — relevant when consumer code passes
+ * `/sessions/s1.json` or `sessions//s1.json`; both end up at
+ * `sessions/s1.json`.
+ */
+export function normalizePath(path) {
+    if (path === '')
+        return '';
+    return path
+        .split('/')
+        .filter((segment) => segment.length > 0)
+        .join('/');
+}
+/**
+ * Join a parent path with a child path, normalizing the result.
+ * Used by the `ref(parent, path)` overload and by `child` helpers.
+ */
+export function joinPaths(parent, child) {
+    const childNorm = normalizePath(child);
+    if (parent === '')
+        return childNorm;
+    if (childNorm === '')
+        return parent;
+    return `${parent}/${childNorm}`;
+}
+/** Structural test — references all expose `fullPath` + `storage`. */
+function isStorageReference(target) {
+    if (target === null || typeof target !== 'object')
+        return false;
+    // Distinguish from a FirebaseStorage handle (which has TARGET_SYMBOL
+    // but no `fullPath`). The handle has the symbol; refs don't.
+    if (TARGET_SYMBOL in target)
+        return false;
+    const obj = target;
+    return typeof obj.fullPath === 'string' && obj.storage !== undefined;
+}
+//# sourceMappingURL=reference.js.map

package/dist/storage/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../src/storage/reference.ts"],"names":[],"mappings":"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"}