pyric-admin 0.1.0-alpha.22 → 0.1.0-alpha.25

package/dist/storage/file-query.js

@@ -0,0 +1,94 @@
+/**
+ * The object listing `@google-cloud/storage`'s `Bucket.getFiles` reads from
+ * the JSON API, worked out over a bucket's object names. Both sandbox arms
+ * collect the names their own way and page them here, so a query lists the
+ * same files on each.
+ *
+ *   - `prefix` matches the start of a name verbatim; it is not a folder, so
+ *     `users/12` matches `users/123/a.png`. An empty prefix lists the bucket.
+ *   - `delimiter` rolls each name whose rest after the prefix holds it up to
+ *     a prefix ending in the delimiter, reported in `apiResponse.prefixes`.
+ *   - A page holds up to `maxResults` entries, files and prefixes together,
+ *     in name order (1000 without it), and `pageToken` resumes after the
+ *     entry the previous page ended on.
+ *   - `autoPaginate` (the default unless `maxResults` is set or it is
+ *     `false`) reads every page, as `@google-cloud/paginator` does.
+ */
+/** The page size the JSON API uses without `maxResults`. */
+const DEFAULT_PAGE_SIZE = 1000;
+/** Refuse the callback form, which would otherwise never be called. */
+export function assertQuery(query, method) {
+    const isCallback = typeof query === 'function';
+    if (isCallback) {
+        throw new TypeError(`pyric-admin/storage: Bucket.${method} returns a promise; the callback form is not supported.`);
+    }
+}
+/** Does this query read every page, as `@google-cloud/paginator` decides? */
+export function readsEveryPage(query) {
+    const limited = typeof query.maxResults === 'number' && query.maxResults > 0;
+    return !limited && query.autoPaginate !== false;
+}
+/** The page of `names` that `query` asks for, `pageSize` entries at most. */
+export function listingPage(names, query, pageSize = pageSizeOf(query)) {
+    const entries = entriesOf(names, query);
+    const after = query.pageToken === undefined ? undefined : decodeToken(query.pageToken);
+    const remaining = after === undefined ? entries : entries.filter(entry => entry.key > after);
+    const page = remaining.slice(0, pageSize);
+    const more = remaining.length > page.length;
+    const last = page[page.length - 1];
+    return {
+        names: page.filter(entry => !entry.rolledUp).map(entry => entry.key),
+        prefixes: page.filter(entry => entry.rolledUp).map(entry => entry.key),
+        ...(more && last !== undefined ? { nextPageToken: encodeToken(last.key) } : {}),
+    };
+}
+/** Every file name `query` lists from its `pageToken` on, up to `maxResults` of them, across pages. */
+export function everyListedName(names, query) {
+    const { maxResults, ...rest } = query;
+    const listed = listingPage(names, rest, Number.POSITIVE_INFINITY).names;
+    const limited = typeof maxResults === 'number' && maxResults > 0;
+    return limited ? listed.slice(0, maxResults) : listed;
+}
+/** The JSON API response for `page`. */
+export function apiResponseOf(page) {
+    return {
+        kind: 'storage#objects',
+        ...(page.prefixes.length > 0 ? { prefixes: page.prefixes } : {}),
+        ...(page.nextPageToken !== undefined ? { nextPageToken: page.nextPageToken } : {}),
+    };
+}
+function pageSizeOf(query) {
+    const limited = typeof query.maxResults === 'number' && query.maxResults > 0;
+    return limited ? Math.min(query.maxResults, DEFAULT_PAGE_SIZE) : DEFAULT_PAGE_SIZE;
+}
+/** The names under the prefix, with the delimiter's roll-up applied, in name order. */
+function entriesOf(names, query) {
+    const prefix = query.prefix ?? '';
+    const delimiter = query.delimiter ?? '';
+    const byKey = new Map();
+    for (const name of names) {
+        if (!name.startsWith(prefix))
+            continue;
+        const rest = name.slice(prefix.length);
+        const cut = delimiter === '' ? -1 : rest.indexOf(delimiter);
+        const rolledUp = cut !== -1;
+        const key = rolledUp ? prefix + rest.slice(0, cut + delimiter.length) : name;
+        byKey.set(key, { key, rolledUp });
+    }
+    return [...byKey.values()].sort((a, b) => compareKeys(a.key, b.key));
+}
+/** Name order, as the JSON API lists objects. */
+function compareKeys(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+function encodeToken(key) {
+    return Buffer.from(key, 'utf8').toString('base64url');
+}
+function decodeToken(token) {
+    return Buffer.from(token, 'base64url').toString('utf8');
+}
+//# sourceMappingURL=file-query.js.map

package/dist/storage/file-query.js.map

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

package/dist/storage/get-files.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `Bucket.getFiles`'s result, as `@google-cloud/storage` resolves it:
+ * `[files, nextQuery, apiResponse]`.
+ *
+ * A single page (`autoPaginate: false`, or `maxResults` set) gives the query
+ * for the next page, with its `pageToken`, or `null` on the last page. Reading
+ * every page gives a copy of the query the call was made with in that
+ * position, as `@google-cloud/paginator` resolves it, and the last page's
+ * response.
+ */
+import { type GetFilesApiResponse, type GetFilesOptions } from './file-query.js';
+export type GetFilesResponse<F> = [F[], GetFilesOptions | null, GetFilesApiResponse];
+/** The `getFiles` result for `query` over a bucket's object `names`. */
+export declare function getFilesResponse<F>(names: readonly string[], query: GetFilesOptions, fileOf: (name: string) => F): GetFilesResponse<F>;
+//# sourceMappingURL=get-files.d.ts.map

package/dist/storage/get-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-files.d.ts","sourceRoot":"","sources":["../../src/storage/get-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI,EAAE,mBAAmB,CAAC,CAAC;AAErF,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAWtI"}

package/dist/storage/get-files.js

@@ -0,0 +1,33 @@
+/**
+ * `Bucket.getFiles`'s result, as `@google-cloud/storage` resolves it:
+ * `[files, nextQuery, apiResponse]`.
+ *
+ * A single page (`autoPaginate: false`, or `maxResults` set) gives the query
+ * for the next page, with its `pageToken`, or `null` on the last page. Reading
+ * every page gives a copy of the query the call was made with in that
+ * position, as `@google-cloud/paginator` resolves it, and the last page's
+ * response.
+ */
+import { apiResponseOf, listingPage, readsEveryPage, } from './file-query.js';
+/** The `getFiles` result for `query` over a bucket's object `names`. */
+export function getFilesResponse(names, query, fileOf) {
+    if (!readsEveryPage(query))
+        return onePage(names, query, fileOf);
+    const files = [];
+    let pageQuery = { ...query };
+    for (;;) {
+        const page = listingPage(names, pageQuery);
+        files.push(...page.names.map(fileOf));
+        const token = page.nextPageToken;
+        if (token === undefined)
+            return [files, { ...query }, apiResponseOf(page)];
+        pageQuery = { ...pageQuery, pageToken: token };
+    }
+}
+function onePage(names, query, fileOf) {
+    const page = listingPage(names, query);
+    const token = page.nextPageToken;
+    const nextQuery = token === undefined ? null : { ...query, pageToken: token };
+    return [page.names.map(fileOf), nextQuery, apiResponseOf(page)];
+}
+//# sourceMappingURL=get-files.js.map

package/dist/storage/get-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-files.js","sourceRoot":"","sources":["../../src/storage/get-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,aAAa,EACb,WAAW,EACX,cAAc,GAGf,MAAM,iBAAiB,CAAC;AAIzB,wEAAwE;AACxE,MAAM,UAAU,gBAAgB,CAAI,KAAwB,EAAE,KAAsB,EAAE,MAA2B;IAC/G,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACjE,MAAM,KAAK,GAAQ,EAAE,CAAC;IACtB,IAAI,SAAS,GAAoB,EAAE,GAAG,KAAK,EAAE,CAAC;IAC9C,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC;QACjC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3E,SAAS,GAAG,EAAE,GAAG,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACjD,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAI,KAAwB,EAAE,KAAsB,EAAE,MAA2B;IAC/F,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC;IACjC,MAAM,SAAS,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC9E,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/storage/index.d.ts

@@ -7,10 +7,15 @@
  *
  *   - **Remote sandbox path** — a handle branded by `@pyric/cli`'
  *     `connectRemoteSandbox()`/`remoteSandbox()` relays every data
- *     operation over the bridge to the browser-hosted SharedWorker's
- *     object store (admin lens pinned — rules bypass). Single bucket;
- *     8 MiB per-op byte cap; `getSignedUrl` stays the local stub. See
- *     the remote arm section below.
+ *     operation to the sandbox's host (admin lens pinned — rules bypass).
+ *     Bytes move over the host's HTTP byte route when it has one, and as
+ *     frames when it does not (a browser tab's SharedWorker). Each bucket
+ *     name is its own bucket on the host; the default bucket is the host's
+ *     default one. `createResumableUpload` gives a session URL on the byte
+ *     route. `getSignedUrl` stays the local stub. See the remote arm section below.
+ *
+ *   - **Default bucket**: `bucket()` is the bucket the app's `storageBucket`
+ *     option names, or `'pyric-default'` without one, on both paths.
  *
  *   - **Sandbox path** — returns an in-process {@link Storage} backed
  *     by an in-memory `Map<bucketName, Map<path, FileEntry>>`. State
@@ -23,17 +28,38 @@
  *       - `storage.bucket(name?)` → {@link Bucket}-shaped handle
  *       - `bucket.file(path)` → {@link File}-shaped handle
  *       - `file.save(data, options?)` — `Buffer | string | Uint8Array`
- *       - `file.download(options?)` → `[Buffer]`
+ *       - `file.download(options?)` → `[Buffer]`, whole or `start..end`
+ *       - `file.createReadStream(options?)`, whole or `start..end`
+ *       - `file.createWriteStream(options?)`
+ *       - `save` and `createWriteStream` take `firebaseStorageDownloadTokens`
+ *         under `metadata.metadata` as the file's download tokens, which grant
+ *         its download URL as `getDownloadURL` mints them
+ *       - `file.getMetadata()` / `file.setMetadata(metadata)`: settable fields
+ *         and custom metadata; a custom key set to `null` is removed
+ *       - `getDownloadURL(file)`: mints a token into
+ *         `firebaseStorageDownloadTokens` when the file has none. The Node
+ *         host returns its HTTP URL; elsewhere the URL is a `data:` URI
  *       - `file.delete()` — idempotent
  *       - `file.exists()` → `[boolean]`
  *       - `file.getSignedUrl(options)` → `['pyric-sandbox-storage://…']`
+ *       - `file.copy(destination, options?)`, within a bucket or across buckets
+ *       - `bucket.getFiles(query?)` → `[files, nextQuery, apiResponse]`, with
+ *         `prefix`, `delimiter`, `maxResults`, `pageToken`, `autoPaginate`
+ *       - `bucket.deleteFiles(query?)`, honoring `force`
  *
  *     **Deferred in the sandbox backend** (throws `"not implemented in
- *     pyric-admin/storage sandbox backend"`): streaming uploads
- *     (`createWriteStream`), resumable uploads, signed cookies, IAM
- *     policies, lifecycle rules, ACLs, copy/move, notifications.
+ *     pyric-admin/storage sandbox backend"`): `file.createResumableUpload`
+ *     upload sessions, which need an HTTP host, signed cookies, IAM
+ *     policies, lifecycle rules, ACLs, move, notifications. Every other
+ *     `Bucket` and `File` method is a deferred member listed in
+ *     `deferred-members.ts`.
  */
+import { Readable, Writable } from 'node:stream';
 import { type PyricAdminApp } from '../app/index.js';
+import { type DeleteFilesOptions, type GetFilesOptions } from './file-query.js';
+import { type GetFilesResponse } from './get-files.js';
+export type { DeleteFilesOptions, GetFilesApiResponse, GetFilesOptions } from './file-query.js';
+export type { GetFilesResponse } from './get-files.js';
 /**
  * `pyric-admin/storage`'s sandbox `Storage` handle. It exposes the subset
  * documented in the module header.
@@ -57,6 +83,18 @@ export interface Bucket {
     readonly name: string;
     /** Get a {@link File} handle for `path`. The file may or may not exist. */
     file(path: string): File;
+    /**
+     * List the bucket's files, as `@google-cloud/storage` does: names starting
+     * with `prefix`, rolled up at `delimiter`, paged by `maxResults` and
+     * `pageToken`. Resolves `[files, nextQuery, apiResponse]`; see `get-files.ts`.
+     */
+    getFiles(query?: GetFilesOptions): Promise<GetFilesResponse<File>>;
+    /**
+     * Delete every file `getFiles(query)` would list across its pages. With
+     * `force`, a failed delete does not stop the others, and the call rejects
+     * with the array of errors.
+     */
+    deleteFiles(query?: DeleteFilesOptions): Promise<void>;
 }
 /**
  * A file handle within a bucket. Method shapes mirror
@@ -64,9 +102,9 @@ export interface Bucket {
  * / getSignedUrl, etc.) so common consumer code retains the familiar shape.
  *
  * The sandbox backend implements the methods documented here. Any
- * other `File` method from `@google-cloud/storage` (`createWriteStream`,
- * `createReadStream`, `copy`, `move`, `setMetadata` beyond the basic
- * `save` options, etc.) throws on the sandbox path — see module header.
+ * other `File` method from `@google-cloud/storage` (`copy`, `move`,
+ * `setMetadata` beyond the basic `save` options, etc.) is not implemented
+ * on the sandbox path — see module header.
  */
 export interface File {
     /** Name (path) of the file within its bucket. */
@@ -82,11 +120,47 @@ export interface File {
      */
     save(data: Buffer | string | Uint8Array, options?: SaveOptions): Promise<void>;
     /**
-     * Read the file's bytes. Returns a `[Buffer]` tuple to mirror
-     * `@google-cloud/storage`'s `File.download` (which returns
-     * `[Buffer, ...]`). Throws if the file does not exist.
+     * Read the file's bytes, or the inclusive range `start..end` of them.
+     * Returns a `[Buffer]` tuple to mirror `@google-cloud/storage`'s
+     * `File.download` (which returns `[Buffer, ...]`). Throws if the file
+     * does not exist.
      */
     download(options?: DownloadOptions): Promise<[Buffer]>;
+    /**
+     * A readable stream of the file's bytes, or of the inclusive range
+     * `start..end`. A missing file surfaces as the stream's error.
+     */
+    createReadStream(options?: CreateReadStreamOptions): Readable;
+    /**
+     * A writable stream whose bytes replace the file's content once the
+     * stream finishes, as {@link File.save} does.
+     */
+    createWriteStream(options?: CreateWriteStreamOptions): Writable;
+    /**
+     * `@google-cloud/storage`'s resumable upload session: a URL that takes the
+     * object's bytes from a browser, and creates the object with
+     * `options.metadata` when the last byte arrives. A remote sandbox whose host
+     * serves HTTP (the hosted dev server) gives one. In process, and on a
+     * browser tab's SharedWorker host, there is no HTTP host to take the bytes,
+     * so this rejects with a not-implemented error there.
+     */
+    createResumableUpload(options?: CreateResumableUploadOptions): Promise<[string]>;
+    /**
+     * Copy the object, with its content type, custom metadata and download
+     * tokens, to `destination`: a path in this bucket, a `gs://` URL, another
+     * {@link Bucket} (same path), or another {@link File}. `options` change the
+     * copy's metadata; a custom key set to `null` is left off the copy.
+     * Resolves `[copy, copyMetadata]`.
+     */
+    copy(destination: CopyDestination, options?: CopyOptions): Promise<[File, FileMetadata]>;
+    /** The file's metadata, as a `[metadata]` tuple. Throws if the file does not exist. */
+    getMetadata(): Promise<[FileMetadata]>;
+    /**
+     * Change the file's metadata: the named settable fields, and the custom
+     * keys under `metadata`, where `null` removes a key and the others stay.
+     * Removing `firebaseStorageDownloadTokens` revokes the file's download URL.
+     */
+    setMetadata(metadata: FileMetadataUpdate): Promise<[FileMetadata]>;
     /**
      * Remove the file from its bucket. Idempotent — deleting a missing
      * file is a no-op (matches `@google-cloud/storage`'s
@@ -107,10 +181,10 @@ export interface File {
 /** Options bag for {@link File.save}. Subset of `@google-cloud/storage`'s `SaveOptions`. */
 export interface SaveOptions {
     /**
-     * Arbitrary metadata stored alongside the file. The sandbox stores
-     * it verbatim; consumers that need to round-trip `contentType`,
-     * `metadata.custom`, etc. get it back via internal admin tooling
-     * (not exposed on `File` itself yet).
+     * Metadata stored alongside the file: the settable fields `setMetadata`
+     * takes, and custom keys under `metadata`. A
+     * `firebaseStorageDownloadTokens` custom key sets the file's download
+     * tokens. Other fields are ignored. Read it back with {@link File.getMetadata}.
      */
     metadata?: Record<string, unknown>;
     /**
@@ -119,17 +193,75 @@ export interface SaveOptions {
      */
     contentType?: string;
     /**
-     * `resumable: false` is the only mode the sandbox models (single-
-     * shot writes). The sandbox throws when set to `true` since resumable
-     * uploads are deferred.
+     * How `@google-cloud/storage` sends the bytes. The sandbox stores the
+     * object in one write either way, so the stored object is the same.
      */
     resumable?: boolean;
 }
 /** Options bag for {@link File.download}. Subset of `@google-cloud/storage`'s `DownloadOptions`. */
 export interface DownloadOptions {
+    /** First byte to read, inclusive. */
+    start?: number;
+    /** Last byte to read, inclusive. */
+    end?: number;
     /** The sandbox accepts but ignores `validation`. */
     validation?: 'md5' | 'crc32c' | boolean;
 }
+/** Options bag for {@link File.createReadStream}. Subset of `@google-cloud/storage`'s `CreateReadStreamOptions`. */
+export type CreateReadStreamOptions = DownloadOptions;
+/** Options bag for {@link File.createWriteStream}. Subset of `@google-cloud/storage`'s `CreateWriteStreamOptions`. */
+export interface CreateWriteStreamOptions {
+    /** Stored alongside the file, as {@link SaveOptions.metadata} is. */
+    metadata?: Record<string, unknown>;
+    /** Content type stored on the file. */
+    contentType?: string;
+}
+/** Options bag for {@link File.createResumableUpload}. Subset of `@google-cloud/storage`'s `CreateResumableUploadOptions`. */
+export interface CreateResumableUploadOptions {
+    /** The object's metadata, as {@link SaveOptions.metadata} takes it. */
+    metadata?: Record<string, unknown>;
+    /** The page origin whose cross-origin requests the session URL answers. */
+    origin?: string;
+}
+/** Where {@link File.copy} copies to. */
+export type CopyDestination = string | Bucket | File;
+/** Options bag for {@link File.copy}. Subset of `@google-cloud/storage`'s `CopyOptions`. */
+export interface CopyOptions {
+    contentType?: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    /** Custom keys for the copy, merged over the source's; `null` leaves a key off. */
+    metadata?: Record<string, string | number | boolean | null>;
+}
+/** Settable fields the sandbox keeps, besides custom metadata. */
+declare const SETTABLE_FIELDS: readonly ["contentType", "cacheControl", "contentDisposition", "contentEncoding", "contentLanguage"];
+type SettableField = (typeof SETTABLE_FIELDS)[number];
+/** A file's metadata. Subset of `@google-cloud/storage`'s `FileMetadata`. */
+export interface FileMetadata {
+    name: string;
+    bucket: string;
+    generation: string;
+    metageneration: string;
+    /** Size in bytes, as a decimal string. */
+    size: string;
+    timeCreated: string;
+    updated: string;
+    contentType?: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    md5Hash?: string;
+    /** Custom metadata, including `firebaseStorageDownloadTokens` once the file has a download URL. Absent when there is none. */
+    metadata?: Record<string, string>;
+}
+/** What {@link File.setMetadata} takes. Subset of `@google-cloud/storage`'s `FileMetadata`. */
+export type FileMetadataUpdate = Partial<Pick<FileMetadata, SettableField>> & {
+    /** Custom keys to set; `null` removes a key. Values are stored as strings. */
+    metadata?: Record<string, string | number | boolean | null>;
+};
 /** Options bag for {@link File.getSignedUrl}. Mirrors `@google-cloud/storage`'s shape. */
 export interface GetSignedUrlOptions {
     /** `'read' | 'write' | 'delete' | 'resumable'`. Sandbox stamps it into the URL only as a hint. */
@@ -157,8 +289,12 @@ export type StorageApp = PyricAdminApp;
  */
 export declare function getStorage(app?: StorageApp): Storage;
 /**
- * Link-compatible mirror of `firebase-admin/storage`'s `getDownloadURL(file)`.
- * Returns a deterministic sandbox storage stub URL from `file.getSignedUrl()`.
+ * Mirror of `firebase-admin/storage`'s `getDownloadURL(file)`. A file without
+ * a download token gets one in `firebaseStorageDownloadTokens`, as production
+ * mints it. On the Node host the URL is its HTTP byte route URL, which serves
+ * ranges and stops working when the token is removed. In process and on a
+ * SharedWorker host there is no HTTP origin, so the URL is a `data:` URI that
+ * carries the bytes.
  */
 export declare function getDownloadURL(file: File): Promise<string>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AASH,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,iBAAiB,CAAC;AAKzB;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,IAAI;IACnB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,qGAAqG;IACrG,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7B;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;CAC/D;AAED,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;CACzC;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;IAClD;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,OAAO,CAuBpD;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"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"}