@capacitor/preferences 4.0.0-beta.0

package/android/src/main/java/com/capacitorjs/plugins/preferences/Preferences.java

@@ -0,0 +1,45 @@
+package com.capacitorjs.plugins.preferences;
+
+import android.app.Activity;
+import android.content.Context;
+import android.content.SharedPreferences;
+import java.util.Set;
+
+public class Preferences {
+
+    private SharedPreferences preferences;
+
+    private interface PreferencesOperation {
+        void execute(SharedPreferences.Editor editor);
+    }
+
+    Preferences(Context context, PreferencesConfiguration configuration) {
+        this.preferences = context.getSharedPreferences(configuration.group, Activity.MODE_PRIVATE);
+    }
+
+    public String get(String key) {
+        return preferences.getString(key, null);
+    }
+
+    public void set(String key, String value) {
+        executeOperation(editor -> editor.putString(key, value));
+    }
+
+    public void remove(String key) {
+        executeOperation(editor -> editor.remove(key));
+    }
+
+    public Set<String> keys() {
+        return preferences.getAll().keySet();
+    }
+
+    public void clear() {
+        executeOperation(SharedPreferences.Editor::clear);
+    }
+
+    private void executeOperation(PreferencesOperation op) {
+        SharedPreferences.Editor editor = preferences.edit();
+        op.execute(editor);
+        editor.apply();
+    }
+}

package/android/src/main/java/com/capacitorjs/plugins/preferences/PreferencesConfiguration.java

@@ -0,0 +1,18 @@
+package com.capacitorjs.plugins.preferences;
+
+public class PreferencesConfiguration implements Cloneable {
+
+    static final PreferencesConfiguration DEFAULTS;
+
+    static {
+        DEFAULTS = new PreferencesConfiguration();
+        DEFAULTS.group = "CapacitorStorage";
+    }
+
+    String group;
+
+    @Override
+    public PreferencesConfiguration clone() throws CloneNotSupportedException {
+        return (PreferencesConfiguration) super.clone();
+    }
+}

package/android/src/main/java/com/capacitorjs/plugins/preferences/PreferencesPlugin.java

@@ -0,0 +1,129 @@
+package com.capacitorjs.plugins.preferences;
+
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import org.json.JSONException;
+
+@CapacitorPlugin(name = "Preferences")
+public class PreferencesPlugin extends Plugin {
+
+    private Preferences preferences;
+
+    @Override
+    public void load() {
+        preferences = new Preferences(getContext(), PreferencesConfiguration.DEFAULTS);
+    }
+
+    @PluginMethod
+    public void configure(PluginCall call) {
+        try {
+            PreferencesConfiguration configuration = PreferencesConfiguration.DEFAULTS.clone();
+            configuration.group = call.getString("group", PreferencesConfiguration.DEFAULTS.group);
+
+            preferences = new Preferences(getContext(), configuration);
+        } catch (CloneNotSupportedException e) {
+            call.reject("Error while configuring", e);
+            return;
+        }
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void get(PluginCall call) {
+        String key = call.getString("key");
+        if (key == null) {
+            call.reject("Must provide key");
+            return;
+        }
+
+        String value = preferences.get(key);
+
+        JSObject ret = new JSObject();
+        ret.put("value", value == null ? JSObject.NULL : value);
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void set(PluginCall call) {
+        String key = call.getString("key");
+        if (key == null) {
+            call.reject("Must provide key");
+            return;
+        }
+
+        String value = call.getString("value");
+        preferences.set(key, value);
+
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void remove(PluginCall call) {
+        String key = call.getString("key");
+        if (key == null) {
+            call.reject("Must provide key");
+            return;
+        }
+
+        preferences.remove(key);
+
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void keys(PluginCall call) {
+        Set<String> keySet = preferences.keys();
+        String[] keys = keySet.toArray(new String[0]);
+
+        JSObject ret = new JSObject();
+        try {
+            ret.put("keys", new JSArray(keys));
+        } catch (JSONException ex) {
+            call.reject("Unable to serialize response.", ex);
+            return;
+        }
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void clear(PluginCall call) {
+        preferences.clear();
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void migrate(PluginCall call) {
+        List<String> migrated = new ArrayList<>();
+        List<String> existing = new ArrayList<>();
+        Preferences oldPreferences = new Preferences(getContext(), PreferencesConfiguration.DEFAULTS);
+
+        for (String key : oldPreferences.keys()) {
+            String value = oldPreferences.get(key);
+            String currentValue = preferences.get(key);
+
+            if (currentValue == null) {
+                preferences.set(key, value);
+                migrated.add(key);
+            } else {
+                existing.add(key);
+            }
+        }
+
+        JSObject ret = new JSObject();
+        ret.put("migrated", new JSArray(migrated));
+        ret.put("existing", new JSArray(existing));
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void removeOld(PluginCall call) {
+        call.resolve();
+    }
+}

package/dist/docs.json

@@ -0,0 +1,348 @@
+{
+  "api": {
+    "name": "PreferencesPlugin",
+    "slug": "preferencesplugin",
+    "docs": "",
+    "tags": [],
+    "methods": [
+      {
+        "name": "configure",
+        "signature": "(options: ConfigureOptions) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "ConfigureOptions"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Configure the preferences plugin at runtime.\n\nOptions that are `undefined` will not be used.",
+        "complexTypes": [
+          "ConfigureOptions"
+        ],
+        "slug": "configure"
+      },
+      {
+        "name": "get",
+        "signature": "(options: GetOptions) => Promise<GetResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "GetOptions"
+          }
+        ],
+        "returns": "Promise<GetResult>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Get the value from preferences of a given key.",
+        "complexTypes": [
+          "GetResult",
+          "GetOptions"
+        ],
+        "slug": "get"
+      },
+      {
+        "name": "set",
+        "signature": "(options: SetOptions) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "SetOptions"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Set the value in preferences for a given key.",
+        "complexTypes": [
+          "SetOptions"
+        ],
+        "slug": "set"
+      },
+      {
+        "name": "remove",
+        "signature": "(options: RemoveOptions) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "RemoveOptions"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Remove the value from preferences for a given key, if any.",
+        "complexTypes": [
+          "RemoveOptions"
+        ],
+        "slug": "remove"
+      },
+      {
+        "name": "clear",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Clear keys and values from preferences.",
+        "complexTypes": [],
+        "slug": "clear"
+      },
+      {
+        "name": "keys",
+        "signature": "() => Promise<KeysResult>",
+        "parameters": [],
+        "returns": "Promise<KeysResult>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Return the list of known keys in preferences.",
+        "complexTypes": [
+          "KeysResult"
+        ],
+        "slug": "keys"
+      },
+      {
+        "name": "migrate",
+        "signature": "() => Promise<MigrateResult>",
+        "parameters": [],
+        "returns": "Promise<MigrateResult>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Migrate data from the Capacitor 2 Storage plugin.\n\nThis action is non-destructive. It will not remove old data and will only\nwrite new data if they key was not already set.\nTo remove the old data after being migrated, call removeOld().",
+        "complexTypes": [
+          "MigrateResult"
+        ],
+        "slug": "migrate"
+      },
+      {
+        "name": "removeOld",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.1.0"
+          }
+        ],
+        "docs": "Removes old data with `_cap_` prefix from the Capacitor 2 Storage plugin.",
+        "complexTypes": [],
+        "slug": "removeold"
+      }
+    ],
+    "properties": []
+  },
+  "interfaces": [
+    {
+      "name": "ConfigureOptions",
+      "slug": "configureoptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "group",
+          "tags": [
+            {
+              "text": "CapacitorStorage",
+              "name": "default"
+            },
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Set the preferences group.\n\nPreferences groups are used to organize key/value pairs.\n\nUsing the value 'NativeStorage' provides backwards-compatibility with\n[`cordova-plugin-nativestorage`](https://www.npmjs.com/package/cordova-plugin-nativestorage).\nWARNING: The `clear()` method can delete unintended values when using the\n'NativeStorage' group.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "GetResult",
+      "slug": "getresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "value",
+          "tags": [
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The value from preferences associated with the given key.\n\nIf a value was not previously set or was removed, value will be `null`.",
+          "complexTypes": [],
+          "type": "string | null"
+        }
+      ]
+    },
+    {
+      "name": "GetOptions",
+      "slug": "getoptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "key",
+          "tags": [
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The key whose value to retrieve from preferences.",
+          "complexTypes": [],
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "name": "SetOptions",
+      "slug": "setoptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "key",
+          "tags": [
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The key to associate with the value being set in preferences.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "value",
+          "tags": [
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The value to set in preferences with the associated key.",
+          "complexTypes": [],
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "name": "RemoveOptions",
+      "slug": "removeoptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "key",
+          "tags": [
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The key whose value to remove from preferences.",
+          "complexTypes": [],
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "name": "KeysResult",
+      "slug": "keysresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "keys",
+          "tags": [
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The known keys in preferences.",
+          "complexTypes": [],
+          "type": "string[]"
+        }
+      ]
+    },
+    {
+      "name": "MigrateResult",
+      "slug": "migrateresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "migrated",
+          "tags": [
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "An array of keys that were migrated.",
+          "complexTypes": [],
+          "type": "string[]"
+        },
+        {
+          "name": "existing",
+          "tags": [
+            {
+              "text": "1.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "An array of keys that were already migrated or otherwise exist in preferences\nthat had a value in the Capacitor 2 Preferences plugin.",
+          "complexTypes": [],
+          "type": "string[]"
+        }
+      ]
+    }
+  ],
+  "enums": [],
+  "typeAliases": [],
+  "pluginConfigs": []
+}

package/dist/esm/definitions.d.ts

@@ -0,0 +1,135 @@
+export interface ConfigureOptions {
+    /**
+     * Set the preferences group.
+     *
+     * Preferences groups are used to organize key/value pairs.
+     *
+     * Using the value 'NativeStorage' provides backwards-compatibility with
+     * [`cordova-plugin-nativestorage`](https://www.npmjs.com/package/cordova-plugin-nativestorage).
+     * WARNING: The `clear()` method can delete unintended values when using the
+     * 'NativeStorage' group.
+     *
+     * @default CapacitorStorage
+     * @since 1.0.0
+     */
+    group?: string;
+}
+export interface GetOptions {
+    /**
+     * The key whose value to retrieve from preferences.
+     *
+     * @since 1.0.0
+     */
+    key: string;
+}
+export interface GetResult {
+    /**
+     * The value from preferences associated with the given key.
+     *
+     * If a value was not previously set or was removed, value will be `null`.
+     *
+     * @since 1.0.0
+     */
+    value: string | null;
+}
+export interface SetOptions {
+    /**
+     * The key to associate with the value being set in preferences.
+     *
+     * @since 1.0.0
+     */
+    key: string;
+    /**
+     * The value to set in preferences with the associated key.
+     *
+     * @since 1.0.0
+     */
+    value: string;
+}
+export interface RemoveOptions {
+    /**
+     * The key whose value to remove from preferences.
+     *
+     * @since 1.0.0
+     */
+    key: string;
+}
+export interface KeysResult {
+    /**
+     * The known keys in preferences.
+     *
+     * @since 1.0.0
+     */
+    keys: string[];
+}
+export interface MigrateResult {
+    /**
+     * An array of keys that were migrated.
+     *
+     * @since 1.0.0
+     */
+    migrated: string[];
+    /**
+     * An array of keys that were already migrated or otherwise exist in preferences
+     * that had a value in the Capacitor 2 Preferences plugin.
+     *
+     * @since 1.0.0
+     */
+    existing: string[];
+}
+export interface PreferencesPlugin {
+    /**
+     * Configure the preferences plugin at runtime.
+     *
+     * Options that are `undefined` will not be used.
+     *
+     * @since 1.0.0
+     */
+    configure(options: ConfigureOptions): Promise<void>;
+    /**
+     * Get the value from preferences of a given key.
+     *
+     * @since 1.0.0
+     */
+    get(options: GetOptions): Promise<GetResult>;
+    /**
+     * Set the value in preferences for a given key.
+     *
+     * @since 1.0.0
+     */
+    set(options: SetOptions): Promise<void>;
+    /**
+     * Remove the value from preferences for a given key, if any.
+     *
+     * @since 1.0.0
+     */
+    remove(options: RemoveOptions): Promise<void>;
+    /**
+     * Clear keys and values from preferences.
+     *
+     * @since 1.0.0
+     */
+    clear(): Promise<void>;
+    /**
+     * Return the list of known keys in preferences.
+     *
+     * @since 1.0.0
+     */
+    keys(): Promise<KeysResult>;
+    /**
+     * Migrate data from the Capacitor 2 Storage plugin.
+     *
+     * This action is non-destructive. It will not remove old data and will only
+     * write new data if they key was not already set.
+     * To remove the old data after being migrated, call removeOld().
+     *
+     * @since 1.0.0
+     */
+    migrate(): Promise<MigrateResult>;
+    /**
+     * Removes old data with `_cap_` prefix from the Capacitor 2 Storage plugin.
+     *
+     * @since 1.1.0
+     */
+    removeOld(): Promise<void>;
+}

package/dist/esm/definitions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface ConfigureOptions {\n  /**\n   * Set the preferences group.\n   *\n   * Preferences groups are used to organize key/value pairs.\n   *\n   * Using the value 'NativeStorage' provides backwards-compatibility with\n   * [`cordova-plugin-nativestorage`](https://www.npmjs.com/package/cordova-plugin-nativestorage).\n   * WARNING: The `clear()` method can delete unintended values when using the\n   * 'NativeStorage' group.\n   *\n   * @default CapacitorStorage\n   * @since 1.0.0\n   */\n  group?: string;\n}\n\nexport interface GetOptions {\n  /**\n   * The key whose value to retrieve from preferences.\n   *\n   * @since 1.0.0\n   */\n  key: string;\n}\n\nexport interface GetResult {\n  /**\n   * The value from preferences associated with the given key.\n   *\n   * If a value was not previously set or was removed, value will be `null`.\n   *\n   * @since 1.0.0\n   */\n  value: string | null;\n}\n\nexport interface SetOptions {\n  /**\n   * The key to associate with the value being set in preferences.\n   *\n   * @since 1.0.0\n   */\n  key: string;\n\n  /**\n   * The value to set in preferences with the associated key.\n   *\n   * @since 1.0.0\n   */\n  value: string;\n}\n\nexport interface RemoveOptions {\n  /**\n   * The key whose value to remove from preferences.\n   *\n   * @since 1.0.0\n   */\n  key: string;\n}\n\nexport interface KeysResult {\n  /**\n   * The known keys in preferences.\n   *\n   * @since 1.0.0\n   */\n  keys: string[];\n}\n\nexport interface MigrateResult {\n  /**\n   * An array of keys that were migrated.\n   *\n   * @since 1.0.0\n   */\n  migrated: string[];\n\n  /**\n   * An array of keys that were already migrated or otherwise exist in preferences\n   * that had a value in the Capacitor 2 Preferences plugin.\n   *\n   * @since 1.0.0\n   */\n  existing: string[];\n}\n\nexport interface PreferencesPlugin {\n  /**\n   * Configure the preferences plugin at runtime.\n   *\n   * Options that are `undefined` will not be used.\n   *\n   * @since 1.0.0\n   */\n  configure(options: ConfigureOptions): Promise<void>;\n\n  /**\n   * Get the value from preferences of a given key.\n   *\n   * @since 1.0.0\n   */\n  get(options: GetOptions): Promise<GetResult>;\n\n  /**\n   * Set the value in preferences for a given key.\n   *\n   * @since 1.0.0\n   */\n  set(options: SetOptions): Promise<void>;\n\n  /**\n   * Remove the value from preferences for a given key, if any.\n   *\n   * @since 1.0.0\n   */\n  remove(options: RemoveOptions): Promise<void>;\n\n  /**\n   * Clear keys and values from preferences.\n   *\n   * @since 1.0.0\n   */\n  clear(): Promise<void>;\n\n  /**\n   * Return the list of known keys in preferences.\n   *\n   * @since 1.0.0\n   */\n  keys(): Promise<KeysResult>;\n\n  /**\n   * Migrate data from the Capacitor 2 Storage plugin.\n   *\n   * This action is non-destructive. It will not remove old data and will only\n   * write new data if they key was not already set.\n   * To remove the old data after being migrated, call removeOld().\n   *\n   * @since 1.0.0\n   */\n  migrate(): Promise<MigrateResult>;\n\n  /**\n   * Removes old data with `_cap_` prefix from the Capacitor 2 Storage plugin.\n   *\n   * @since 1.1.0\n   */\n  removeOld(): Promise<void>;\n}\n"]}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+import type { PreferencesPlugin } from './definitions';
+declare const Preferences: PreferencesPlugin;
+export * from './definitions';
+export { Preferences };

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+import { registerPlugin } from '@capacitor/core';
+const Preferences = registerPlugin('Preferences', {
+    web: () => import('./web').then(m => new m.PreferencesWeb()),
+});
+export * from './definitions';
+export { Preferences };
+//# sourceMappingURL=index.js.map