-
-
+
+
# Files for Meteor.js
-Stable, fast, robust, and well-maintained Meteor.js package for files management using MongoDB Collection API. What does exactly this means? Calling [`.insert()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/insert.md) method would initiate a file upload and then insert new record into collection. Calling [`.remove()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/remove.md) method would erase stored file and record from MongoDB Collection. And so on, no need to learn new APIs. It's flavored with extra low-level methods like [`.unlink()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/unlink.md) and [`.write()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/write.md) for complex integrations.
+Stable, fast, robust, and well-maintained Meteor.js package for files management using MongoDB Collection API. Call [`.insertAsync()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/insertAsync.md) method to initiate a file upload and to insert new record into MongoDB collection after upload is complete. Calling [`.removeAsync()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/removeAsync.md) method would erase stored file and record from MongoDB Collection. And so on, no need to learn new APIs. Hackable via hooks and events. Supports uploads to AWS:S3, GridFS, Google Storage, DropBox, and other 3rd party storage.
## ToC:
- [π Documentation](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/toc.md) - Docs, API, Demos, Examples
+- [β¨ Key features](https://github.com/veliovgroup/Meteor-Files#key-features)
+- [π API Documentation](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/readme.md)
- __β‘οΈ Quick start__:
- [π§ Installation](https://github.com/veliovgroup/Meteor-Files#installation)
- - [π¨βπ» API examples](https://github.com/veliovgroup/Meteor-Files#api-overview):
- - [Initialize Collection](https://github.com/veliovgroup/Meteor-Files#new-filescollectionconfig-isomorphic)
- - [Upload file](https://github.com/veliovgroup/Meteor-Files#insertsettings-autostart-client)
- - [Stream files](https://github.com/veliovgroup/Meteor-Files#stream-files)
- - [Download Button](https://github.com/veliovgroup/Meteor-Files#download-button)
-- [π¦ Related Packages](https://github.com/veliovgroup/Meteor-Files#related-packages)
-- [β¨ Key features](https://github.com/veliovgroup/Meteor-Files#key-features)
-- [πββοΈ Help / Support](https://github.com/veliovgroup/Meteor-Files#get-support)
+ - [π¨βπ» Usage example](https://github.com/veliovgroup/Meteor-Files#api-overview)
- [π€ FAQ](https://github.com/veliovgroup/Meteor-Files#faq)
- [π
Awards](https://github.com/veliovgroup/Meteor-Files#awards)
-- [π€ Help & Contribute](https://github.com/veliovgroup/Meteor-Files#contribution)
+- [πββοΈ Get Help](https://github.com/veliovgroup/Meteor-Files#get-support)
+- [ποΈ Demo applications](https://github.com/veliovgroup/Meteor-Files#demo-applications)
+- [π¦ Related Packages](https://github.com/veliovgroup/Meteor-Files#related-packages)
- [π Support this project](https://github.com/veliovgroup/Meteor-Files#support-meteor-files-project)
+- [π¨βπ» Contribute to this project](https://github.com/veliovgroup/Meteor-Files#contribution)
- [π Supporters](https://github.com/veliovgroup/Meteor-Files#supporters)
## Key features
- Compatible with all front-end frameworks from Blaze to [React](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/react-example.md)
- Upload via `HTTP` and `DDP` transports, [read about difference](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/about-transports.md)
-- Sustainable and "resumable" uploads will resume upon connection interruption or server reboot
+- Sustainable and "resumable" uploads will auto-resume when connection interrupted or server rebooted
- Upload files through computing cloud without persistent File System, like Heroku (*"resumable" uploads are not supported on Heroku and alike*)
- Use *[GridFS](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/gridfs-bucket-integration.md#use-gridfs-with-gridfsbucket-as-a-storage)*, *[AWS S3](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/aws-s3-integration.md)*, *[Google Storage](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/google-cloud-storage-integration.md)* or *[DropBox](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/dropbox-integration.md)* and other (*[3rd-party storage](hhttps://github.com/veliovgroup/Meteor-Files/blob/master/docs/3rd-party-storage.md)*)
- APIs for checking file mime-type, size, extension, an other file's properties before upload using *[`onBeforeUpload` hook](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/constructor.md)*
-- APIs for [resizing images](https://github.com/veliovgroup/meteor-files-website/blob/master/imports/server/image-processing.js#L19), *[subversions management](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/file-subversions.md)*, and other post-processing tasks using *[`onAfterUpload` hook](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/constructor.md)*
+- APIs for [resizing images](https://github.com/veliovgroup/meteor-files-website/blob/master/imports/server/image-processing.js#L19), *[subversions management](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/file-subversions.md)*, and other post-processing tasks using *[`onAfterUpload`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/constructor.md)* and *[`onAfterRemove`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/constructor.md)* hooks
## Installation:
@@ -59,24 +56,31 @@ import { FilesCollection } from 'meteor/ostrio:files';
For detailed docs, examples, and API β read [documentation section](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/readme.md).
-- [`FilesCollection` Constructor](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/constructor.md) [*Isomorphic*] - Initialize FilesCollection
-- [`insert()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/insert.md) [*Client*] - Upload file(s) from client to server
-- [`find()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/find.md) [*Isomorphic*] - Create cursor for FilesCollection
-- [`remove()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/remove.md) [*Isomorphic*] - Remove files from FilesCollection and "unlink" (e.g. remove) from FS
-- [`findOne()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/findOne.md) [*Isomorphic*] - Find one file in FilesCollection
-- [`write()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/write.md) [*Server*] - Write `Buffer` to FS and FilesCollection
-- [`load()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/load.md) [*Server*] - Write file to FS and FilesCollection from remote URL
+__Main methods:__
+
+- [`FilesCollection` Constructor](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/constructor.md) [*Anywhere*] - Initialize FilesCollection
+- [`insertAsync()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/insertAsync.md) [*Client*] - Upload a file to server, returns `FileUpload` instance
+- [`link()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/link.md) [*Anywhere*] - Generate downloadable link
+- [`find()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/find.md) [*Anywhere*] - Find all files matching selector, returns [`FilesCursor` instance](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/FilesCursor.md)
+- [`findOneAsync()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/findOneAsync.md) [*Anywhere*] - Find a single file record matching selector, returns [`FileCursor` instance](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/FileCursor.md)
+- [`removeAsync()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/removeAsync.md) [*Anywhere*] - Asynchronously remove files from FilesCollection and "unlink" (e.g. remove) from Server
- [`addFile()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/addFile.md) [*Server*] - Add local file to FilesCollection from FS
-- [`unlink()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/unlink.md) [*Server*] - "Unlink" (e.g. remove) file from FS
-- [`link()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/link.md) [*Isomorphic*] - Generate downloadable link
+- [`loadAsync()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/loadAsync.md) [*Server*] - Write file to FS and FilesCollection from remote URL
+- [`writeAsync()`](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/writeAsync.md) [*Server*] - Write `Buffer` to FS and FilesCollection
-### `new FilesCollection([config])` [*Isomorphic*]
+### Constructor
-Read full docs for [`FilesCollection` Constructor](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/constructor.md)
+__[*Anywhere*]__. Initiate file's collection in the similar way to `Mongo.Collection` with optional settings related to file-uploads. Read full docs for [`FilesCollection` Constructor in the API documentation](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/constructor.md).
-Shared code:
+```js
+import { FilesCollection } from 'meteor/ostrio:files';
+new FilesCollection(FilesCollectionConfig);
+```
+
+Pass additional options to control upload-flow
```js
+// shared: /imports/lib/collections/images.collection.js
import { Meteor } from 'meteor/meteor';
import { FilesCollection } from 'meteor/ostrio:files';
@@ -93,19 +97,27 @@ const imagesCollection = new FilesCollection({
});
if (Meteor.isClient) {
+ // SUBSCRIBE TO ALL UPLOADED FILES ON THE CLIENT
Meteor.subscribe('files.images.all');
}
if (Meteor.isServer) {
+ // PUBLISH ALL UPLOADED FILES ON THE SERVER
Meteor.publish('files.images.all', function () {
- return imagesCollection.find().cursor;
+ return imagesCollection.collection.find();
});
}
```
-### `insert(settings[, autoStart])` [*Client*]
+### Upload a file
-Read full docs for [`insert()` method](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/insert.md)
+```ts
+import { FilesCollection } from 'meteor/ostrio:files';
+const files = new FilesCollection(FilesCollectionConfig);
+files.insertAsync(config: InsertOptions, autoStart?: boolean): Promise
+
## Get Support:
@@ -339,12 +360,18 @@ For more expressive example see [Download demo](https://github.com/veliovgroup/M
- [Releases / Changelog / History](https://github.com/veliovgroup/Meteor-Files/releases)
- For more docs and examples [read wiki](https://github.com/veliovgroup/Meteor-Files/blob/master/docs/readme.md)
-## Demo application:
+## Demo applications:
-Fully-featured file-sharing app
+Fully-featured file-sharing app:
- [Live: __files.veliov.com__](https://files.veliov.com)
-- [Source Code Rep](https://github.com/veliovgroup/meteor-files-website#file-sharing-web-app)
+- [Source Code Rep](https://github.com/veliovgroup/meteor-files-website)
+
+Other demos:
+
+- [Simplest Upload demo app](https://github.com/veliovgroup/Meteor-Files-Demos/tree/master/demo-simplest-upload)
+- [Simplest Download demo](https://github.com/veliovgroup/Meteor-Files-Demos/tree/master/demo-simplest-download-button)
+- [Simplest Streaming demo app](https://github.com/veliovgroup/Meteor-Files-Demos/tree/master/demo-simplest-streaming)
## Related Packages:
@@ -353,12 +380,12 @@ Fully-featured file-sharing app
## Support Meteor-Files project:
-- Star on [GitHub](https://github.com/veliovgroup/Meteor-Files)
-- Star on [Atmosphere](https://atmospherejs.com/ostrio/files)
-- Share via [Facebook](https://www.facebook.com/sharer.php?u=https%3A%2F%2Fgithub.com%2Fveliovgroup%2FMeteor-Files) and [Twitter](https://twitter.com/share?url=https%3A%2F%2Fgithub.com%2Fveliovgroup%2FMeteor-Files)
-- [Sponsor via GitHub](https://github.com/sponsors/dr-dimitru)
-- [Support via PayPal](https://paypal.me/veliovgroup) β support my open source contributions once or on regular basis
-- Use [ostr.io](https://ostr.io) β [Monitoring](https://snmp-monitoring.com), [Analytics](https://ostr.io/info/web-analytics), [WebSec](https://domain-protection.info), [Web-CRON](https://web-cron.info) and [Pre-rendering](https://prerendering.com) for a website
+- ποΈ Upload and share files using [meteor-files.com](https://meteor-files.com/?ref=github-files-repo-footer) β Continue interrupted file uploads without losing any progress. There is nothing that will stop Meteor from delivering your file to the desired destination
+- π¨βπ» Improve your project using [ostr.io](https://ostr.io?ref=github-files-repo-footer) for [Server Monitoring](https://snmp-monitoring.com), [Web Analytics](https://ostr.io/info/web-analytics?ref=github-files-repo-footer), [WebSec](https://domain-protection.info), [Web-CRON](https://web-cron.info) and [SEO Pre-rendering](https://prerendering.com)
+- π΅ [Sponsor via GitHub](https://github.com/sponsors/dr-dimitru)
+- π΅ [Support via PayPal](https://paypal.me/veliovgroup)
+- βοΈ Star on [GitHub](https://github.com/veliovgroup/Meteor-Files)
+- βοΈ Star on [Atmosphere](https://atmospherejs.com/ostrio/files)
## Contribution:
diff --git a/client.js b/client.js
index a5f0f467..8a578fab 100644
--- a/client.js
+++ b/client.js
@@ -5,34 +5,32 @@ import { Cookies } from 'meteor/ostrio:cookies';
import { check, Match } from 'meteor/check';
import { UploadInstance } from './upload.js';
import FilesCollectionCore from './core.js';
-import { formatFleURL, helpers } from './lib.js';
+import { formatFileURL, helpers } from './lib.js';
const NOOP = () => { };
const allowedParams = ['allowClientCode', 'allowQueryStringCookies', 'chunkSize', 'collection', 'collectionName', 'ddp', 'debug', 'disableSetTokenCookie', 'disableUpload', 'downloadRoute', 'namingFunction', 'onBeforeUpload', 'onbeforeunloadMessage', 'public', 'sanitize', 'schema'];
/**
- * @locus Anywhere
+ * @locus Client
* @class FilesCollection
- * @param config {Object} - [Both] Configuration object with next properties:
- * @param config.debug {Boolean} - [Both] Turn on/of debugging and extra logging
- * @param config.ddp {Object} - [Client] Custom DDP connection. Object returned form `DDP.connect()`
- * @param config.schema {Object} - [Both] Collection Schema
- * @param config.public {Boolean} - [Both] Store files in folder accessible for proxy servers, for limits, and more - read docs`
- * @param config.chunkSize {Number} - [Both] Upload chunk size, default: 524288 bytes (0,5 Mb)
- * @param config.downloadRoute {String} - [Both] Server Route used to retrieve files
- * @param config.collection {Mongo.Collection} - [Both] Mongo Collection Instance
- * @param config.collectionName {String} - [Both] Collection name
- * @param config.namingFunction {Function}- [Both] Function which returns `String`
- * @param config.onBeforeUpload {Function}- [Both] Function which executes on server after receiving each chunk and on client right before beginning upload. Function context is `File` - so you are able to check for extension, mime-type, size and etc.
- * return `true` to continue
- * return `false` or `String` to abort upload
- * @param config.allowClientCode {Boolean} - [Both] Allow to run `remove` from client
- * @param config.onbeforeunloadMessage {String|Function} - [Client] Message shown to user when closing browser's window or tab while upload process is running
- * @param config.disableUpload {Boolean} - Disable file upload, useful for server only solutions
- * @param config.disableSetTokenCookie {Boolean} - Disable cookie setting. Useful when you use multiple file collections or when you want to implement your own authorization.
- * @param config.allowQueryStringCookies {Boolean} - Allow passing Cookies in a query string (in URL). Primary should be used only in Cordova environment. Note: this option will be used only on Cordova. Default: `false`
- * @param config.sanitize {Function} - Override default sanitize function
- * @summary Create new instance of FilesCollection
+ * @param config {FilesCollectionConfig} - [anywhere] configuration object with the following properties:
+ * @param config.debug {boolean} - [anywhere] turn on/off debugging and extra logging
+ * @param config.ddp {DDP.DDPStatic} - [client] custom DDP connection; object returned from `DDP.connect()`
+ * @param config.schema {object} - [anywhere] collection schema
+ * @param config.public {boolean} - [anywhere] store files in folder accessible for proxy servers, for limits, etc.
+ * @param config.chunkSize {number} - [anywhere] upload chunk size, default: 524288 bytes (0.5 mb)
+ * @param config.downloadRoute {string} - [anywhere] server route used to retrieve files
+ * @param config.collection {Mongo.Collection} - [anywhere] mongo collection instance
+ * @param config.collectionName {string} - [anywhere] collection name
+ * @param config.namingFunction {function} - [anywhere] function that returns a string
+ * @param config.onBeforeUpload {function} - [anywhere] function executed on server after receiving each chunk and on client before starting upload; return `true` to continue, `false` or `string` (error message) to abort
+ * @param config.allowClientCode {boolean} - [anywhere] allow to run remove from client
+ * @param config.onbeforeunloadMessage {string|function} - [client] message shown to user when closing window/tab during upload
+ * @param config.disableUpload {boolean} - disable file upload; useful for server-only solutions
+ * @param config.disableSetTokenCookie {boolean} - disable cookie setting; useful when using multiple file collections or custom authorization
+ * @param config.allowQueryStringCookies {boolean} - allow passing cookies in query string (primarily in cordova); default: false
+ * @param config.sanitize {function} - override default sanitize function
+ * @summary Creates a new instance of FilesCollection
*/
class FilesCollection extends FilesCollectionCore {
constructor(config) {
@@ -47,8 +45,9 @@ class FilesCollection extends FilesCollectionCore {
const self = this;
const cookie = new Cookies({
- allowQueryStringCookies: this.allowQueryStringCookies
+ allowQueryStringCookies: this.allowQueryStringCookies,
});
+
if (!helpers.isBoolean(this.debug)) {
this.debug = false;
}
@@ -116,7 +115,7 @@ class FilesCollection extends FilesCollectionCore {
if (!config.disableSetTokenCookie) {
const setTokenCookie = () => {
if (Meteor.connection._lastSessionId) {
- cookie.set('x_mtok', Meteor.connection._lastSessionId, { path: '/', sameSite: 'Lax' });
+ cookie.set('x_mtok', Meteor.connection._lastSessionId, { path: '/', sameSite: 'Lax', secure: Meteor.isProduction });
if ((Meteor.isCordova || Meteor.isDesktop) && this.allowQueryStringCookies) {
cookie.send();
}
@@ -133,6 +132,7 @@ class FilesCollection extends FilesCollectionCore {
}
}
+ // eslint-disable-next-line new-cap
check(this.onbeforeunloadMessage, Match.OneOf(String, Function));
try {
@@ -161,8 +161,10 @@ class FilesCollection extends FilesCollectionCore {
check(this.chunkSize, Number);
check(this.downloadRoute, String);
check(this.disableUpload, Boolean);
+ /* eslint-disable new-cap */
check(this.namingFunction, Match.OneOf(false, Function));
check(this.onBeforeUpload, Match.OneOf(false, Function));
+ /* eslint-enable new-cap */
check(this.allowClientCode, Boolean);
check(this.ddp, Match.Any);
@@ -175,12 +177,12 @@ class FilesCollection extends FilesCollectionCore {
}
/**
+ * Returns file's mime-type.
* @locus Anywhere
* @memberOf FilesCollection
* @name _getMimeType
- * @param {Object} fileData - File Object
- * @summary Returns file's mime-type
- * @returns {String}
+ * @param {FileData} fileData - file object
+ * @returns {string}
*/
_getMimeType(fileData) {
let mime;
@@ -188,7 +190,6 @@ class FilesCollection extends FilesCollectionCore {
if (helpers.isObject(fileData)) {
mime = fileData.type;
}
-
if (!mime || !helpers.isString(mime)) {
mime = 'application/octet-stream';
}
@@ -196,11 +197,12 @@ class FilesCollection extends FilesCollectionCore {
}
/**
+ * Returns an object with user's information.
* @locus Anywhere
* @memberOf FilesCollection
* @name _getUser
- * @summary Returns object with `userId` and `user()` method which return user's object
- * @returns {Object}
+ * @summary Returns an object with userId and a user() method that returns the user object
+ * @returns {ContextUser}
*/
_getUser() {
const result = {
@@ -219,58 +221,96 @@ class FilesCollection extends FilesCollectionCore {
}
/**
+ * Uploads a file to the server over DDP or HTTP.
* @locus Client
* @memberOf FilesCollection
* @name insert
* @see https://developer.mozilla.org/en-US/docs/Web/API/FileReader
- * @param {Object} config - Configuration object with next properties:
- * {File|Object} file - HTML5 `files` item, like in change event: `e.currentTarget.files[0]`
- * {String} fileId - Optional `fileId` used at insert
- * {Object} meta - Additional data as object, use later for search
- * {Boolean} allowWebWorkers- Allow/Deny WebWorkers usage
- * {Number|dynamic} chunkSize - Chunk size for upload
- * {String} transport - Upload transport `http` or `ddp`
- * {Object} ddp - Custom DDP connection. Object returned form `DDP.connect()`
- * {Function} onUploaded - Callback triggered when upload is finished, with two arguments `error` and `fileRef`
- * {Function} onStart - Callback triggered when upload is started after all successful validations, with two arguments `error` (always null) and `fileRef`
- * {Function} onError - Callback triggered on error in upload and/or FileReader, with two arguments `error` and `fileData`
- * {Function} onProgress - Callback triggered when chunk is sent, with only argument `progress`
- * {Function} onBeforeUpload - Callback triggered right before upload is started:
- * return true to continue
- * return false to abort upload
- * @param {Boolean} autoStart - Start upload immediately. If set to false, you need manually call .start() method on returned class. Useful to set EventListeners.
- * @summary Upload file to server over DDP or HTTP
- * @returns {UploadInstance} Instance. UploadInstance has next properties:
- * {ReactiveVar} onPause - Is upload process on the pause?
- * {ReactiveVar} state - active|paused|aborted|completed
- * {ReactiveVar} progress - Current progress in percentage
- * {Function} pause - Pause upload process
- * {Function} continue - Continue paused upload process
- * {Function} toggle - Toggle continue/pause if upload process
- * {Function} abort - Abort upload
- * {Function} readAsDataURL - Current file as data URL, use to create image preview and etc. Be aware of big files, may lead to browser crash
+ * @param {InsertOptions} config - configuration object with properties:
+ * {File} file - HTML5 file object (e.g. from e.currentTarget.files[0])
+ * {string} fileId - optional fileId used at insert
+ * {MetadataType} meta - additional data as an object, used later for search
+ * {boolean} allowWebWorkers - allow/deny use of web workers
+ * {number|string} chunkSize - chunk size for upload (or 'dynamic')
+ * {MeteorFilesTransportType} transport - upload transport ('http' or 'ddp')
+ * {DDP.DDPStatic} ddp - custom DDP connection (returned from DDP.connect())
+ * {function} onUploaded - callback triggered when upload finishes; receives (error, fileObj)
+ * {function} onStart - callback triggered when upload starts; receives (error, fileObj) (error always null)
+ * {function} onError - callback triggered on error during upload/FileReader; receives (error, fileData)
+ * {function} onProgress - callback triggered when a chunk is sent; receives (progress)
+ * {function} onBeforeUpload - callback triggered before upload starts; return true to continue, false or string to abort
+ * @param {boolean} [autoStart=true] - whether to start upload immediately (if false, call .start() manually)
+ * @summary Uploads a file to the server over DDP or HTTP
+ * @returns {FileUpload|UploadInstance} An instance with properties:
+ * {ReactiveVar} onPause - whether the upload is paused
+ * {ReactiveVar} state - 'active' | 'paused' | 'aborted' | 'completed'
+ * {ReactiveVar} progress - upload progress (percentage)
+ * {function} pause - pauses the upload
+ * {function} continue - continues a paused upload
+ * {function} toggle - toggles pause/continue
+ * {function} abort - aborts the upload
+ * {function} readAsDataURL - returns the file as a data URL (for preview); note: big files may crash the browser
*/
insert(config, autoStart = true) {
+ this._debug('[FilesCollection] [insert()]', config, { autoStart });
if (this.disableUpload) {
- Meteor._debug('[FilesCollection] [insert()] Upload is disabled with [disableUpload]!');
- return {};
+ this._debug('[FilesCollection] [insert()] Upload is disabled with [disableUpload]!');
+ config.disableUpload = true;
}
- return (new UploadInstance(config, this))[autoStart ? 'start' : 'manual']();
+
+ const uploadInstance = new UploadInstance(config, this);
+ if (autoStart) {
+ uploadInstance.start().catch((error) => {
+ uploadInstance.emit('error', new Meteor.Error(500, '[FilesCollection] [insert] Error starting upload:', error));
+ });
+ return uploadInstance;
+ }
+
+ return uploadInstance.manual();
}
/**
- * @locus Anywhere
+ * Asynchronously uploads a file to the server over DDP or HTTP.
+ * @locus Client
+ * @memberOf FilesCollection
+ * @name insertAsync
+ * @param {InsertOptions} config - configuration object with properties:
+ * @param {boolean} [autoStart=true] - whether to start upload immediately (if false, call .start() manually)
+ * @returns {Promise
- Usefull when you want to auth user based on custom cookie (or other way).
- Must return null or {userId: null || String, user: function=> null || user }
+ Useful when you want to auth user based on custom cookie (or other way).
+ Must return null or {userId: null|String, userAsync: function => Promise<e;null|user>e; }
|
| + Param/Type + | ++ Description + | ++ Comment + | +
|---|---|---|
| + `settings` {*InsertOptions*} + | ++ [REQUIRED] + | ++ See all options below + | +
| + `settings.file` {*File*} or {*Object*} or {*String*} + | ++ [REQUIRED] HTML5 `files` item + | +
+ Ex.: From event: `event.currentTarget.files[0]`
+ + Set to dataURI {*String*} for Base64 + |
+
| + `settings.fileId` {*String*} + | ++ Explicitly set the fileId for the file + | ++ This is an optional parameters `Random.id()` will be used otherwise + | +
| + `settings.fileName` {*String*} + | ++ [REQUIRED] only for `base64` uploads + | ++ For regular uploads this option is [OPTIONAL], will replace default file's name provided in HTML5 `files` item + | +
| + `settings.isBase64` {*Boolean*} + | ++ Upload as `base64` string. For example when image data read from `canvas` + | ++ See Examples + | +
| + `settings.meta` {*Object*} + | ++ Additional file-related data + | ++ Ex.: `ownerId`, `postId`, etc. + | +
| + `settings.transport` {*String*} + | ++ Must be set to + `http` or `ddp` + | +
+ Note: upload via `http` is at least twice faster. `HTTP` will properly work only with "sticky sessions"
+ + Default: `ddp` + |
+
| + `settings.ddp` {*Object*} + | ++ Custom DDP connection for upload. Object returned form `DDP.connect()` + | ++ By default `Meteor` (The default DDP connection) + | +
| + `settings.onStart` {*Function*} + | +
+ Callback, triggered when upload is started and validations was successful + Arguments: +
|
+ + |
| + `settings.onUploaded` {*Function*} + | +
+ Callback, triggered when upload is finished + Arguments: +
|
+ + |
| + `settings.onAbort` {*Function*} + | +
+ Callback, triggered when `abort()` method is called + Arguments: +
|
+ + |
| + `settings.onError` {*Function*} + | +
+ Callback, triggered when upload finished with error + Arguments: +
|
+ + |
| + `settings.onProgress` {*Function*} + | +
+ Callback, triggered after chunk is sent + Arguments: +
|
+ + |
| + `settings.onBeforeUpload` {*Function*} + | +
+ Callback, triggered right before upload is started + Arguments: +
|
+
+ Use to check file-type, extension, size, etc.
+
|
+
| + `settings.chunkSize` {*Number*|dynamic} + | ++ Chunk size for upload + | ++ `dynamic` is recommended + | +
| + `settings.allowWebWorkers` {*Boolean*} + | ++ Use WebWorkers (*To avoid main thread blocking*) whenever feature is available in browser + | ++ Default: `true` + | +
| + `autoStart` {*Boolean*} + | ++ Start upload immediately + | +
+ If set to `false` `.insertAsync()` method will return `FileUpload` class instance with `.start()` method that needs to get called to actually start an upload. + Set to `false` to set *EventListeners* before starting and upload. Default: `true` + When set to `true` (*default*) `.insertAsync()` method will return `UploadInstance` class instance, where `UploadInstance.result` will be `FileUpload` class instance + |
+
| + Name/Type + | ++ Description + | ++ Comment + | +
|---|---|---|
| + `file` {*File*} + | ++ Source file passed into `insertAsync()` method + | ++ |
| + `onPause` {*ReactiveVar*} + | ++ Is upload process on the pause? + | ++ |
| + `progress` {*ReactiveVar*} + | ++ Upload progress in percents + | ++ `0` - `100` + | +
| + `pause()` {*Function*} + | ++ Pause upload process + | ++ |
| + `continue()` {*Function*} + | ++ Continue paused upload process + | ++ |
| + `toggle()` {*Function*} + | ++ Toggle `continue`/`pause` if upload in the progress + | ++ |
| + `async abort()` {*AsyncFunction*} + | ++ Abort current upload, then trigger `onAbort` callback + | ++ |
| + `pipe()` {*Function*} + | ++ Pipe data before upload + | ++ All data must be in `data URI` scheme (*Base64*) + | +
| + `estimateTime` {*ReactiveVar*} + | ++ Remaining upload time in milliseconds + | ++ |
| + `estimateSpeed` {*ReactiveVar*} + | ++ Current upload speed in bytes/second + | ++ To convert into speed, take a look on filesize package, usage: `filesize(estimateSpeed, {bits: true}) + '/s';` + | +
| + `state` {*ReactiveVar*} + | ++ String, indicates current state of the upload + | +
+
|
+
| + Name + | ++ Description + | ++ Comment + | +
|---|---|---|
| + `start` + | +
+ Triggered when upload is started (*before sending first byte*) and validations was successful. + Arguments: +
|
+ + |
| + `data` + | +
+ Triggered after each chunk is read. + Arguments: +
|
+ + Can be used to display previews or do something else with loaded file during upload. To get EOF use `readEnd` event + | +
| + `readEnd` + | ++ Triggered after file is fully read by browser + | ++ Has no arguments + | +
| + `progress` + | +
+ Triggered after each chunk is sent. + Arguments: +
|
+ + |
| + `pause` + | +
+ Triggered after upload process set to pause. + Arguments: +
|
+ + |
| + `continue` + | +
+ Triggered after upload process is continued from pause. + Arguments: +
|
+ + |
| + `abort` + | +
+ Triggered after upload is aborted. + Arguments: +
|
+ + |
| + `uploaded` + | +
+ Triggered when upload is finished. + Arguments: +
|
+ + |
| + `error` + | +
+ Triggered whenever upload has an error. + Arguments: +
|
+ + |
| + `end` + | +
+ Triggered at the very end of upload or by `.abort()`. + In case if `end` triggered by `.abort()`, the server could return a `408` response code. + Arguments: +
|
+ + |