Add option to exclude Realm file from iCloud backup

CHANGELOG.md

@@ -4,7 +4,7 @@
 * None
 
 ### Enhancements
-* None
+* Added option to exclude realm files from iCloud backup ([#4139](https://github.com/realm/realm-js/issues/4139))
 
 ### Fixed
 * <How to hit and notice issue? what was the impact?> ([#????](https://github.com/realm/realm-js/issues/????), since v?.?.?)

contrib/building.md

@@ -384,9 +384,8 @@ export NVM_DIR="$HOME/.nvm"
 
 ## Testing against real apps
 
-There are a couple of suggested workflows for testing your changes to Realm JS against real apps:
+Here's the suggested workflow for testing your changes to Realm JS against real apps:
 
-- [Guide: Setting up watchman to copy changes from this package to an app](guide-watchman.md)
 - [Guide: Testing your changes against sample apps using a script](guide-testing-with-sample-apps.md)
 
 ## Debugging

packages/realm/bindgen/js_opt_in_spec.yml

@@ -51,6 +51,7 @@ records:
       - initialization_function
       - should_compact_on_launch_function
       - automatically_handle_backlinks_in_migrations
+      - exclude_from_icloud_backup
 
   UserIdentity:
     fields:
@@ -238,6 +239,7 @@ classes:
       - remove_file
       - remove_directory
       - get_cpu_arch
+      - after_realm_open
 
   WeakSyncSession:
     methods:

packages/realm/bindgen/js_spec.yml

@@ -15,6 +15,7 @@ classes:
       remove_file: '(path: const std::string&)'
       remove_directory: '(path: const std::string&)'
       get_cpu_arch: () -> std::string
+      after_realm_open: '(sharedRealm: std::shared_ptr<Realm>)'
       # print: (const char* fmt, ...) # can't expose varargs directly. Could expose a fixed overload.
 
   WeakSyncSession:

packages/realm/binding/android/src/main/cpp/platform.cpp

@@ -115,6 +115,8 @@ void JsPlatformHelpers::print(const char* fmt, ...)
     va_end(vl);
 }
 
+void JsPlatformHelpers::after_realm_open(const std::shared_ptr<Realm>) {}
+
 std::string JsPlatformHelpers::get_cpu_arch()
 {
 #if defined(__arm__)

packages/realm/binding/apple/platform.mm

@@ -18,6 +18,7 @@
 
 #include "../platform.hpp"
 
+#include <memory>
 #include <realm/util/to_string.hpp>
 
 #include <stdarg.h>
@@ -35,6 +36,10 @@
   return error.localizedDescription;
 }
 
+static void RLMAddSkipBackupAttributeToItemAtPath(std::string_view path) {
+    [[NSURL fileURLWithPath:@(path.data())] setResourceValue:@YES forKey:NSURLIsExcludedFromBackupKey error:nil];
+}
+
 static std::string s_default_realm_directory;
 
 namespace realm {
@@ -158,6 +163,18 @@
     }
 }
 
+void JsPlatformHelpers::after_realm_open(const std::shared_ptr<Realm> sharedRealm) {
+     if(sharedRealm->config().exclude_from_icloud_backup) {
+       RLMAddSkipBackupAttributeToItemAtPath(sharedRealm->config().path);
+       RLMAddSkipBackupAttributeToItemAtPath(sharedRealm->config().path +
+                                             ".lock");
+       RLMAddSkipBackupAttributeToItemAtPath(sharedRealm->config().path +
+                                             ".note");
+       RLMAddSkipBackupAttributeToItemAtPath(sharedRealm->config().path +
+                                                ".management");
+     }
+}
+
 void JsPlatformHelpers::remove_directory(const std::string &path)
 {
     remove_file(path); // works for directories too

packages/realm/binding/node/platform.cpp

@@ -219,6 +219,11 @@ void JsPlatformHelpers::print(const char* fmt, ...)
     va_end(vl);
 }
 
+void JsPlatformHelpers::after_realm_open(const std::shared_ptr<Realm>)
+{
+    // no-op
+}
+
 // this should never be called
 std::string JsPlatformHelpers::get_cpu_arch()
 {

packages/realm/binding/platform.hpp

@@ -19,6 +19,7 @@
 #pragma once
 
 #include <string>
+#include "realm/object-store/shared_realm.hpp"
 
 namespace realm {
 //
@@ -54,5 +55,8 @@ class JsPlatformHelpers {
 
     // print something
     static void print(const char* fmt, ...);
+
+    // runs after the realm has been opened
+    static void after_realm_open(const std::shared_ptr<Realm> sharedRealm);
 };
 } // namespace realm

packages/realm/src/Configuration.ts

@@ -160,6 +160,12 @@ export type BaseConfiguration = {
    */
   onFirstOpen?: (realm: Realm) => void;
   migrationOptions?: MigrationOptions;
+  /**
+   * Specifies if this Realm should be excluded from iCloud backup.
+   * @default false
+   * @since 12.13.3
+   */
+  excludeFromIcloudBackup?: boolean;
 };
 
 export type ConfigurationWithSync = BaseConfiguration & {

packages/realm/src/Realm.ts

@@ -423,13 +423,14 @@ export class Realm {
     const normalizedSchema = config.schema && normalizeRealmSchema(config.schema);
     const schemaExtras = Realm.extractRealmSchemaExtras(normalizedSchema || []);
     const path = Realm.determinePath(config);
-    const { fifoFilesFallbackPath, shouldCompact, inMemory } = config;
+    const { fifoFilesFallbackPath, shouldCompact, inMemory, excludeFromIcloudBackup } = config;
     const bindingSchema = normalizedSchema && toBindingSchema(normalizedSchema);
     return {
       schemaExtras,
       bindingConfig: {
         path,
         cache: true,
+        excludeFromIcloudBackup,
         fifoFilesFallbackPath,
         schema: bindingSchema,
         inMemory: inMemory === true,
@@ -579,6 +580,8 @@ export class Realm {
       this.schemaExtras = schemaExtras || {};
     }
 
+    binding.JsPlatformHelpers.afterRealmOpen(this.internal);
+
     Object.defineProperty(this, "classes", {
       enumerable: false,
       configurable: false,