Skip to content

Add url param to getStorage and update public Metadata types #4340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 26, 2021
Merged

Add url param to getStorage and update public Metadata types #4340

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
97d8fb5
Add url string arg and update metadata type
hsubox76 Jan 25, 2021
d548587
Fix compat
hsubox76 Jan 25, 2021
95c6bd3
Fix nonoptional metadata properties
hsubox76 Jan 25, 2021
6801043
Undo extraneous api doc updates
hsubox76 Jan 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions common/api-review/storage.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,16 @@

import { FirebaseApp } from '@firebase/app';
import { FirebaseStorageError } from '@firebase/storage-types/exp';
import { FullMetadata } from '@firebase/storage-types/exp';
import { ListOptions } from '@firebase/storage-types/exp';
import { ListResult } from '@firebase/storage-types/exp';
import { Metadata } from '@firebase/storage-types/exp';
import { SettableMetadata } from '@firebase/storage-types/exp';
import { StorageObserver } from '@firebase/storage-types/exp';
import { StorageReference } from '@firebase/storage-types/exp';
import { StorageService } from '@firebase/storage-types/exp';
import { TaskEvent } from '@firebase/storage-types/exp';
import { TaskState } from '@firebase/storage-types/exp';
import { UploadMetadata } from '@firebase/storage-types/exp';
import { UploadResult } from '@firebase/storage-types/exp';
import { UploadTask } from '@firebase/storage-types/exp';

Expand All @@ -22,14 +24,16 @@ export function deleteObject(ref: StorageReference): Promise<void>;

export { FirebaseStorageError }

export { FullMetadata }

// @public
export function getDownloadURL(ref: StorageReference): Promise<string>;

// @public
export function getMetadata(ref: StorageReference): Promise<Metadata>;
export function getMetadata(ref: StorageReference): Promise<FullMetadata>;

// @public
export function getStorage(app: FirebaseApp): StorageService;
export function getStorage(app: FirebaseApp, url?: string): StorageService;

// @public
export function list(ref: StorageReference, options?: ListOptions): Promise<ListResult>;
Expand All @@ -41,14 +45,14 @@ export { ListOptions }

export { ListResult }

export { Metadata }

// @public
export function ref(storage: StorageService, url?: string): StorageReference;

// @public
export function ref(storageOrRef: StorageService | StorageReference, path?: string): StorageReference;

export { SettableMetadata }

export { StorageObserver }

export { StorageReference }
Expand All @@ -71,18 +75,20 @@ export { TaskEvent }
export { TaskState }

// @public
export function updateMetadata(ref: StorageReference, metadata: Partial<Metadata>): Promise<Metadata>;
export function updateMetadata(ref: StorageReference, metadata: SettableMetadata): Promise<FullMetadata>;

// @public
export function uploadBytes(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: Metadata): Promise<UploadResult>;
export function uploadBytes(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): Promise<UploadResult>;

// @public
export function uploadBytesResumable(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: Metadata): UploadTask;
export function uploadBytesResumable(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): UploadTask;

export { UploadMetadata }

export { UploadResult }

// @public
export function uploadString(ref: StorageReference, value: string, format?: string, metadata?: Metadata): Promise<UploadResult>;
export function uploadString(ref: StorageReference, value: string, format?: string, metadata?: UploadMetadata): Promise<UploadResult>;

export { UploadTask }

Expand Down
98 changes: 54 additions & 44 deletions packages/storage-types/exp/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,102 +121,112 @@ export interface ListResult {
}

/**
* The full set of object metadata, including read-only properties.
* Object metadata that can be set at any time.
* @public
*/
export interface Metadata {
export interface SettableMetadata {
/**
* The bucket this object is contained in.
* Served as the 'Cache-Control' header on object download.
*/
bucket: string;
cacheControl?: string | undefined;

/**
* The full path of this object.
* Served as the 'Content-Disposition' header on object download.
*/
fullPath: string;
contentDisposition?: string | undefined;

/**
* The object's generation.
* {@link https://cloud.google.com/storage/docs/generations-preconditions}
* Served as the 'Content-Encoding' header on object download.
*/
generation: string;
contentEncoding?: string | undefined;

/**
* The object's metageneration.
* {@link https://cloud.google.com/storage/docs/generations-preconditions}
* Served as the 'Content-Language' header on object download.
*/
metageneration: string;
contentLanguage?: string | undefined;

/**
* The short name of this object, which is the last component of the full path.
* For example, if fullPath is 'full/path/image.png', name is 'image.png'.
* Served as the 'Content-Type' header on object download.
*/
name: string;
contentType?: string | undefined;

/**
* The size of this object, in bytes.
* Additional user-defined custom metadata.
*/
size: number;

customMetadata?:
| {
[key: string]: string;
}
| undefined;
}
/**
* Object metadata that can be set at upload.
* @public
*/
export interface UploadMetadata extends SettableMetadata {
/**
* A date string representing when this object was created.
* A Base64-encoded MD5 hash of the object being uploaded.
*/
timeCreated: string;
md5Hash?: string | undefined;
}

/**
* The full set of object metadata, including read-only properties.
* @public
*/
export interface FullMetadata extends UploadMetadata {
/**
* A date string representing when this object was last updated.
* The bucket this object is contained in.
*/
updated: string;
bucket?: string;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is not used for metadata that is returned from the backed, it should no longer be optional.

Copy link
Contributor Author

@hsubox76 hsubox76 Jan 25, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this guaranteed to always be returned from the backend? Is there a list of metadata properties that always come back from the backend?

Oh I guess I could just always go off the previous documentation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like there is a list here: https://cloud.google.com/storage/docs/json_api/v1/objects#resource


/**
* A Base64-encoded MD5 hash of the object being uploaded.
* The full path of this object.
*/
md5Hash: string | undefined;
fullPath?: string;

/**
* Served as the 'Cache-Control' header on object download.
* The object's generation.
* {@link https://cloud.google.com/storage/docs/generations-preconditions}
*/
cacheControl: string | undefined;
generation?: string;

/**
* Served as the 'Content-Disposition' header on object download.
* The object's metageneration.
* {@link https://cloud.google.com/storage/docs/generations-preconditions}
*/
contentDisposition: string | undefined;
metageneration?: string;

/**
* Served as the 'Content-Encoding' header on object download.
* The short name of this object, which is the last component of the full path.
* For example, if fullPath is 'full/path/image.png', name is 'image.png'.
*/
contentEncoding: string | undefined;
name?: string;

/**
* Served as the 'Content-Language' header on object download.
* The size of this object, in bytes.
*/
contentLanguage: string | undefined;
size?: number;

/**
* Served as the 'Content-Type' header on object download.
* A date string representing when this object was created.
*/
contentType: string | undefined;
timeCreated?: string;

/**
* Tokens to allow access to the downloatd URL.
* A date string representing when this object was last updated.
*/
downloadTokens: string[] | undefined;
updated?: string;

/**
* Additional user-defined custom metadata.
* Tokens to allow access to the downloatd URL.
*/
customMetadata:
| {
[key: string]: string;
}
| undefined;
downloadTokens?: string[] | undefined;

/**
* `StorageReference` associated with this upload.
*/
ref: StorageReference | undefined;
[prop: string]: unknown;
ref?: StorageReference | undefined;
}

/**
Expand Down
2 changes: 1 addition & 1 deletion packages/storage/compat/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ registerStorage(firebase as _FirebaseNamespace);
declare module '@firebase/app-types' {
interface FirebaseNamespace {
storage?: {
(app?: FirebaseApp): types.FirebaseStorage;
(app?: FirebaseApp, url?: string): types.FirebaseStorage;
Storage: typeof types.FirebaseStorage;

StringFormat: {
Expand Down
40 changes: 21 additions & 19 deletions packages/storage/exp/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,15 +41,17 @@ import { name, version } from '../package.json';
import {
StorageReference,
StorageService,
Metadata,
UploadResult,
ListOptions,
ListResult,
UploadTask,
FirebaseStorageError,
TaskEvent,
TaskState,
StorageObserver
StorageObserver,
SettableMetadata,
UploadMetadata,
FullMetadata
} from '@firebase/storage-types/exp';
import { Metadata as MetadataInternal } from '../src/metadata';
import {
Expand All @@ -71,7 +73,9 @@ import {
export {
StorageReference,
StorageService,
Metadata,
UploadMetadata,
SettableMetadata,
FullMetadata,
UploadResult,
ListOptions,
ListResult,
Expand All @@ -88,13 +92,13 @@ export {
* @public
* @param ref - StorageReference where data should be uploaded.
* @param data - The data to upload.
* @param metadata - Metadata for the newly uploaded data.
* @param metadata - Metadata for the data to upload.
* @returns A Promise containing an UploadResult
*/
export function uploadBytes(
ref: StorageReference,
data: Blob | Uint8Array | ArrayBuffer,
metadata?: Metadata
metadata?: UploadMetadata
): Promise<UploadResult> {
return uploadBytesInternal(
ref as Reference,
Expand All @@ -110,14 +114,14 @@ export function uploadBytes(
* @param ref - StorageReference where string should be uploaded.
* @param value - The string to upload.
* @param format - The format of the string to upload.
* @param metadata - Metadata for the newly uploaded string.
* @param metadata - Metadata for the string to upload.
* @returns A Promise containing an UploadResult
*/
export function uploadString(
ref: StorageReference,
value: string,
format?: string,
metadata?: Metadata
metadata?: UploadMetadata
): Promise<UploadResult> {
return uploadStringInternal(
ref as Reference,
Expand All @@ -133,13 +137,13 @@ export function uploadString(
* @public
* @param ref - StorageReference where data should be uploaded.
* @param data - The data to upload.
* @param metadata - Metadata for the newly uploaded data.
* @param metadata - Metadata for the data to upload.
* @returns An UploadTask
*/
export function uploadBytesResumable(
ref: StorageReference,
data: Blob | Uint8Array | ArrayBuffer,
metadata?: Metadata
metadata?: UploadMetadata
): UploadTask {
return uploadBytesResumableInternal(
ref as Reference,
Expand All @@ -155,8 +159,8 @@ export function uploadBytesResumable(
* @public
* @param ref - StorageReference to get metadata from.
*/
export function getMetadata(ref: StorageReference): Promise<Metadata> {
return getMetadataInternal(ref as Reference) as Promise<Metadata>;
export function getMetadata(ref: StorageReference): Promise<FullMetadata> {
return getMetadataInternal(ref as Reference) as Promise<FullMetadata>;
}

/**
Expand All @@ -166,18 +170,16 @@ export function getMetadata(ref: StorageReference): Promise<Metadata> {
* @param metadata - The new metadata for the object.
* Only values that have been explicitly set will be changed. Explicitly
* setting a value to null will remove the metadata.
* @returns A promise that resolves
* with the new metadata for this object.
* See `firebaseStorage.Reference.prototype.getMetadata`
* @returns A promise that resolves with the new metadata for this object.
*/
export function updateMetadata(
ref: StorageReference,
metadata: Partial<Metadata>
): Promise<Metadata> {
metadata: SettableMetadata
): Promise<FullMetadata> {
return updateMetadataInternal(
ref as Reference,
metadata as Partial<MetadataInternal>
) as Promise<Metadata>;
) as Promise<FullMetadata>;
}

/**
Expand Down Expand Up @@ -294,13 +296,13 @@ const STORAGE_TYPE = 'storage-exp';
* @param app - Firebase app to get Storage instance for.
* @returns A Firebase StorageService instance.
*/
export function getStorage(app: FirebaseApp): StorageService {
export function getStorage(app: FirebaseApp, url?: string): StorageService {
// Dependencies
const storageProvider: Provider<'storage-exp'> = _getProvider(
app,
STORAGE_TYPE
);
const storageInstance = storageProvider.getImmediate();
const storageInstance = storageProvider.getImmediate({ identifier: url });
return storageInstance;
}

Expand Down
Loading