Adding documentation, TS definition and change log.

CHANGELOG.md

@@ -1,3 +1,15 @@
+x.x.x Release notes (yyyy-MM-dd)
+=============================================================
+### Breaking changes
+* `Realm.Sync.initialize()` must be called prior to any interaction with any Realm Object Server.
+
+### Enhancements
+* None.
+
+### Bug fixes
+* None.
+
+
 2.0.0 Release notes (2017-9-26)
 =============================================================
 ### Breaking changes

docs/sync.js

@@ -20,6 +20,11 @@
  * @memberof Realm
  */
 class Sync {
+    /**
+     * Initialize the interaction with Realm Object Server. It should only be called once.
+     */
+    static initialize() {}
+
     /**
      * Add a sync listener to listen to changes across multiple Realms
      * @param {string} server_url - the sync server to listen to
@@ -135,7 +140,7 @@ class User {
      * @param {function(error, user)} [callback] - called with the following arguments:
      *   - `error` - an Error object is provided on failure
      *   - `user` - a valid User object on success
-     * @returns {void|Promise<User>} Returns a promise with a user if the callback was not specified 
+     * @returns {void|Promise<User>} Returns a promise with a user if the callback was not specified
      */
     static login(server, username, password, callback) {}
 
@@ -149,7 +154,7 @@ class User {
      * @param {function(error, User)} [callback] - an optional callback called with the following arguments:
      *   - `error` - an Error object is provided on failure
      *   - `user` - a valid User object on success
-     * @return {void|Promise<User>} Returns a promise with a user if the callback was not specified 
+     * @return {void|Promise<User>} Returns a promise with a user if the callback was not specified
      */
     static registerWithProvider(server, options, callback) {}
 
@@ -161,7 +166,7 @@ class User {
      * @param {function(error, user)} [callback] - called with the following arguments:
      *   - `error` - an Error object is provided on failure
      *   - `user` - a valid User object on success
-     * @return {void|Promise<User>} Returns a promise with a user if the callback was not specified 
+     * @return {void|Promise<User>} Returns a promise with a user if the callback was not specified
      */
     static register(server, username, password, callback) {}
 
@@ -248,7 +253,7 @@ class User {
      * @param {string} recipient the optional recipient of the permission. Can be either
      * 'any' which is the default, or 'currentUser' or 'otherUser' if you want only permissions
      * belonging to the user or *not* belonging to the user.
-     * @returns {Results} a queryable collection of permission objects that provides detailed 
+     * @returns {Results} a queryable collection of permission objects that provides detailed
      * information regarding the granted access.
      * The collection is a live query similar to what you would get by callig Realm.objects,
      * so the same features apply - you can listen for notifications or filter it.
@@ -261,22 +266,22 @@ class User {
      * This should be an object, containing either the key 'userId', or 'metadataKey' and 'metadataValue'.
      * @param {string} realmUrl - The path to the Realm that you want to apply permissions to.
      * @param {string} accessLevel - The access level you want to set: 'none', 'read', 'write' or 'admin'.
-     * @returns {Promise} a Promise that, upon completion, indicates that the permissions have been 
+     * @returns {Promise} a Promise that, upon completion, indicates that the permissions have been
-     * successfully applied by the server. It will be resolved with the 
+     * successfully applied by the server. It will be resolved with the
      * {@link PermissionChange PermissionChange} object that refers to the applied permission.
      */
     applyPermissions(condition, realmUrl, accessLevel) { }
 
     /**
      * Generates a token that can be used for sharing a Realm.
-     * @param {string} realmUrl - The Realm URL whose permissions settings should be changed. Use * to change 
+     * @param {string} realmUrl - The Realm URL whose permissions settings should be changed. Use * to change
      * the permissions of all Realms managed by this user.
-     * @param {string} accessLevel - The access level to grant matching users. Note that the access level 
+     * @param {string} accessLevel - The access level to grant matching users. Note that the access level
-     * setting is additive, i.e. you cannot revoke permissions for users who previously had a higher access level. 
+     * setting is additive, i.e. you cannot revoke permissions for users who previously had a higher access level.
      * Can be 'read', 'write' or 'admin'.
      * @param {Date} [expiresAt] - Optional expiration date of the offer. If set to null, the offer doesn't expire.
      * @returns {string} - A token that can be shared with another user, e.g. via email or message and then consumed by
-     * User.acceptPermissionOffer to obtain permissions to a Realm. 
+     * User.acceptPermissionOffer to obtain permissions to a Realm.
      */
     offerPermissions(realmUrl, accessLevel, expiresAt) { }
 
@@ -291,9 +296,9 @@ class User {
      * Invalidates a permission offer.
      * Invalidating an offer prevents new users from consuming its token. It doesn't revoke any permissions that have
      * already been granted.
-     * @param {string|PermissionOffer} permissionOfferOrToken - Either the token or the entire 
+     * @param {string|PermissionOffer} permissionOfferOrToken - Either the token or the entire
-     * {@link PermissionOffer PermissionOffer} object that was generated with 
+     * {@link PermissionOffer PermissionOffer} object that was generated with
-     * {@link Realm#Sync#User#offerPermissions offerPermissions}. 
+     * {@link Realm#Sync#User#offerPermissions offerPermissions}.
      */
     invalidatePermissionOffer(permissionOfferOrToken) { }
 }
@@ -338,7 +343,7 @@ class Session {
     /**
      * Register a progress notification callback on a session object
      * @param {string} direction - The progress direction to register for.
-     * Can be either: 
+     * Can be either:
      *  - `download` - report download progress
      *  - `upload` - report upload progress
      * @param {string} mode - The progress notification mode to use for the registration.
@@ -405,12 +410,12 @@ class Adapter {
 }
 
 /**
- * The following Instructions can be returned by `Adapter.current(path)`. Each instruction object has 
+ * The following Instructions can be returned by `Adapter.current(path)`. Each instruction object has
  * a `type` property which is one of the following types. For each type below we list the other properties
  * that will exist in the instruction object.
  * @typedef Realm.Sync.Adapter~Instruction
  * @type {(INSERT|SET|DELETE|CLEAR|CHANGE_IDENTITY|LIST_SET|LIST_INSERT|LIST_ERASE|LIST_CLEAR|ADD_TYPE|ADD_PROPERTY)}
- * @property INSERT - insert a new object 
+ * @property INSERT - insert a new object
  * - `object_type` - type of the object being inserted
  * - `identity` - primary key value or row index for the object
  * - `values` - map of property names and property values for the object to insert
@@ -423,7 +428,7 @@ class Adapter {
  * - `identity` - primary key value or row index for the object
  * @property CLEAR - delete all objects of a given type
  * - `object_type` - type of the object
- * @property LIST_SET - set the object at a given list index to an object 
+ * @property LIST_SET - set the object at a given list index to an object
  * - `object_type` - type of the object
  * - `identity` - primary key for the object
  * - `property` - property name for the list property to mutate

lib/index.d.ts

@@ -288,7 +288,7 @@ declare namespace Realm.Sync {
         openManagementRealm(): Realm;
         retrieveAccount(provider: string, username: string): Promise<Account>;
 
-        getGrantedPermissions(recipient: 'any' | 'currentUser' | 'otherUser'): Results<Permission>;
+        getGrantedPermissions(recipient: 'any' | 'currentUser' | 'otherUser'): Results<Permission>;
         applyPermissions(condition: PermissionCondition, realmUrl: string, accessLevel: AccessLevel): Promise<PermissionChange>;
         offerPermissions(realmUrl: string, accessLevel: AccessLevel, expiresAt?: Date): Promise<string>;
         acceptPermissionOffer(token: string): Promise<string>
@@ -296,49 +296,49 @@ declare namespace Realm.Sync {
     }
 
     type PermissionCondition = {
-      userId: string  |
+        userId: string |
-      { metadataKey: string, metadataValue: string }
+        { metadataKey: string, metadataValue: string }
     };
 
-    type AccessLevel = 'none' | 'read' | 'write' | 'admin';
+    type AccessLevel = 'none' | 'read' | 'write' | 'admin';
 
     class Permission {
-      readonly id: string;
+        readonly id: string;
-      readonly updatedAt: Date;
+        readonly updatedAt: Date;
-      readonly userId: string;
+        readonly userId: string;
-      readonly path: string;
+        readonly path: string;
-      readonly mayRead?: boolean;
+        readonly mayRead?: boolean;
-      readonly mayWrite?: boolean;
+        readonly mayWrite?: boolean;
-      readonly mayManage?: boolean;
+        readonly mayManage?: boolean;
     }
 
     class PermissionChange {
-      id: string;
+        id: string;
-      createdAt: Date;
+        createdAt: Date;
-      updatedAt: Date;
+        updatedAt: Date;
-      statusCode?: number;
+        statusCode?: number;
-      statusMessage?: string;
+        statusMessage?: string;
-      userId: string;
+        userId: string;
-      metadataKey?: string;
+        metadataKey?: string;
-      metadataValue?: string;
+        metadataValue?: string;
-      realmUrl: string;
+        realmUrl: string;
-      mayRead?: boolean;
+        mayRead?: boolean;
-      mayWrite?: boolean;
+        mayWrite?: boolean;
-      mayManage?: boolean;
+        mayManage?: boolean;
     }
 
     class PermissionOffer {
-      id: string;
+        id: string;
-      createdAt: Date;
+        createdAt: Date;
-      updatedAt: Date;
+        updatedAt: Date;
-      statusCode?: number;
+        statusCode?: number;
-      statusMessage?: string;
+        statusMessage?: string;
-      token?: string;
+        token?: string;
-      realmUrl: string;
+        realmUrl: string;
-      mayRead?: boolean;
+        mayRead?: boolean;
-      mayWrite?: boolean;
+        mayWrite?: boolean;
-      mayManage?: boolean;
+        mayManage?: boolean;
-      expiresAt?: Date;
+        expiresAt?: Date;
     }
 
     type ErrorCallback = (message?: string, isFatal?: boolean, category?: string, code?: number) => void;
@@ -396,6 +396,7 @@ declare namespace Realm.Sync {
     function removeListener(regex: string, name: string, changeCallback: (changeEvent: ChangeEvent) => void): void;
     function setLogLevel(logLevel: 'all' | 'trace' | 'debug' | 'detail' | 'info' | 'warn' | 'error' | 'fatal' | 'off'): void;
     function setFeatureToken(token: string): void;
+    function initialize(): void;
 
     /**
      * @deprecated, to be removed in 2.0
@@ -436,8 +437,8 @@ declare namespace Realm.Sync {
 }
 
 
-interface ProgressPromise  extends Promise<Realm> {
+interface ProgressPromise extends Promise<Realm> {
-    progress(callback: Realm.Sync.ProgressNotificationCallback) : Promise<Realm>
+    progress(callback: Realm.Sync.ProgressNotificationCallback): Promise<Realm>
 }
 
 declare class Realm {

src/js_sync.hpp

@@ -651,7 +651,7 @@ void SyncClass<T>::initialize(ContextType ctx, FunctionType, ObjectType this_obj
     // setup synced realmFile paths
     ensure_directory_exists_for_file(default_realm_file_directory());
     SyncManager::shared().configure_file_system(default_realm_file_directory(), SyncManager::MetadataMode::NoEncryption);
-    return_value.set(Nan::Undefined());
+    return_value.set_undefined();
 }
 } // js
 } // realm