{"id":13729912,"url":"https://github.com/dre0dru/LocalStorage","last_synced_at":"2025-05-08T02:30:52.455Z","repository":{"id":49057251,"uuid":"350108842","full_name":"dre0dru/LocalStorage","owner":"dre0dru","description":"Configurable generic class for managing local data saved on device.","archived":false,"fork":false,"pushed_at":"2023-12-17T15:39:43.000Z","size":150,"stargazers_count":38,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-07T03:15:20.338Z","etag":null,"topics":["library","serialization","unity","upm-package"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dre0dru.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-03-21T20:18:50.000Z","updated_at":"2024-07-02T04:48:23.000Z","dependencies_parsed_at":"2024-01-11T13:20:07.120Z","dependency_job_id":null,"html_url":"https://github.com/dre0dru/LocalStorage","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dre0dru%2FLocalStorage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dre0dru%2FLocalStorage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dre0dru%2FLocalStorage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dre0dru%2FLocalStorage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dre0dru","download_url":"https://codeload.github.com/dre0dru/LocalStorage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252986622,"owners_count":21836196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","serialization","unity","upm-package"],"created_at":"2024-08-03T02:01:07.392Z","updated_at":"2025-05-08T02:30:52.143Z","avatar_url":"https://github.com/dre0dru.png","language":"C#","funding_links":[],"categories":["C#"],"sub_categories":[],"readme":"[![openupm](https://img.shields.io/npm/v/com.dre0dru.localstorage?label=openupm\u0026registry_uri=https://package.openupm.com)](https://openupm.com/packages/com.dre0dru.localstorage/)\n# Description\nConfigurable generic classes for managing local data saved on device.\nUnity 2020.1+\n\n## Features\n- Two generic classes with configuration options for data read/write and serialization/deserialization via file system or player prefs.\n- Simple file provider that just reads/writes data.\n- Data transformations that allow to preprocess data on read/write:\n  - `IDataTransform` that uses `AES` encryption to encrypt/decrypt data.\n  - `IDataTransform` that uses `GZip` or `Deflate` to compress/decompress data.\n- Json serialization provider that uses `JsonUtility` for serialization.\n- File storage saves data to `Application.persistentDataPath`.\n- Player prefs storage saves data to `PlayerPrefs`. Data location depends on device, refer to [Unity](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html) documentation.\n- Easy to use and understand abstractions that allow to create custom serialization/deserialization and data transformation processes.  \n- Async/sync API.\n- Optional [UniTask](https://github.com/Cysharp/UniTask) support for async API.\n# Installation\nThis package can be installed as unity module directly from git url in two ways:\n- By adding following line in `Packages/manifest.json`:\n```\n\"com.dre0dru.localstorage\": \"https://github.com/dre0dru/LocalStorage.git#upm\",\n```\n- By using `Window/Package Manager/Add package from git URL...` in Unity:\n```\nhttps://github.com/dre0dru/LocalStorage.git#upm\n```\n- The package is also available on the [openupm registry](https://openupm.com/packages/com.dre0dru.localstorage/). You can install it via [openupm-cli](https://github.com/openupm/openupm-cli):\n```\nopenupm add com.dre0dru.localstorage\n```\n## Optional UniTask support\n[UniTask](https://github.com/Cysharp/UniTask) package can be installed to convert async API from using `Task` to `UniTask`. No further actions are required after installation.\n\n`UniTask` support can be disabled by using `DISABLE_UNITASK_SUPPORT` define.\n# Usage\n## FileStorage usage\n```c#\n//Serialization/deserialization implementation\nISerializationProvider serializationProvider = new UnityJsonSerializationProvider();\n\n//Path to save/load from (optional)\nstring path = \"dataFolder\";  //Resulting path will be Application.persistentDataPath/dataFolder\n//File save/load implementation\nIFileProvider fileProvider = new FileProvider(path);\n\nIFileStorage storage = new FileStorage(serializationProvider, fileProvider);\n\nstring fileName = \"fileName.extension\";\n\n//Resulting path will be Application.persistentDataPath/dataFolder/fileName.extension\nstring filePath = storage.GetFilePath(fileName);\n\n//Serializes data then saves file\nstorage.Save(new Vector2(1.0f, 1.0f), fileName);\n\n//Async saving\nawait storage.SaveAsync(new Vector2(1.0f, 1.0f), fileName);\n\n//Check if file exists\nbool exists = storage.FileExists(fileName);\n\n//Loads file then deserializes data\nVector2 deserialized = storage.Load\u003cVector2\u003e(fileName);\n\n//Async loading\nVector2 deserialized = await storage.LoadAsync\u003cVector2\u003e(fileName);\n\n//Deletes file if present\nstorage.Delete(fileName);\n```\n## PlayerPrefsStorage usage\n```c#\n//Serialization/deserialization implementation\nISerializationProvider serializationProvider = new UnityJsonSerializationProvider();\n\nIPlayerPrefsStorage storage = new PlayerPrefsStorage(serializationProvider);\n\nstring dataKey = \"key\";\n\n//Serializes data using ISerializationProvider then puts it into PlayerPrefs under provided key\nstorage.SetData(dataKey, new Vector2(1, 1));\n\n//Async saving\nawait storage.SetDataAsync(dataKey, new Vector2(1, 1));\n\n//Loads data from PlayerPrefs by key then deserializes using ISerializationProvider\nVector2 deserialized = storage.GetData\u003cVector2\u003e(dataKey);\n\n//Async loading\nVector2 deserialized = await storage.GetDataAsync\u003cVector2\u003e(dataKey);\n```\nThe rest of `IPlayerPrefsStorage` API mimics [Unity](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html) `PlayerPrefs` API.\n\n**Warning!** `PlayerPrefsStorage` is not thread safe.\n## Data transformation usage\n`IDataTransform` implementations can be used to preprocess data during serialization/deserialization process.\nAvailable data transformations are:\n- `AesEncryptionDataTransform`\n- `DeflateDataTransform`\n- `GZipDataTransform`\n```c#\n//This is just an example, don't generate new key/IV every time\npublic class ExampleEncryptionSettings : IEncryptionSettings\n{\n    public byte[] Key { get; private set; }\n    public byte[] InitializationVector { get; private set; }\n\n    public ExampleEncryptionSettings()\n    {\n        //Create AES instance\n        using var aes = Aes.Create();\n        //Save AES key somewhere\n        Key = aes.Key;\n        //Save AES IV somewhere\n        InitializationVector = aes.IV;\n    }\n}\n\n//Encryption settings for AES\nIEncryptionSettings encryptionSettings = new ExampleEncryptionSettings();\n\n//Setup desired IDataTransform implementation\nIDataTransform encryptionDataTransform = new AesEncryptionDataTransform(encryptionSettings);\n\n//Base ISerializationProvider that will be used before/after data transform is applied\nISerializationProvider baseSP = new UnityJsonSerializationProvider();\n\n//Setup ISerializationProvider that will use target data transformation during serialization/deserialization process\nISerializationProvider transformSerializationProvider =\n    new DataTransformSerializationProvider(baseSP, encryptionDataTransform);\n\n//Use DataTransformSerializationProvider with FileStorage\nIFileProvider fp = new FileProvider();\nIFileStorage fileStorage = new FileStorage(transformSerializationProvider, fp);\n\n//Or with PlayerPrefsStorage\nIPlayerPrefsStorage playerPrefsStorage = new PlayerPrefsStorage(transformSerializationProvider);\n```\nYou can combine multiple `IDataTransform` to create chained data transformations:\n```c#\nIEncryptionSettings encryptionSettings = new ExampleEncryptionSettings();\n\n//Encryption data transform\nIDataTransform encryptionDataTransform = new AesEncryptionDataTransform(encryptionSettings);\n\n//Compression data transform\nIDataTransform compressionDataTransform = new GZipDataTransform();\n\n//Create combined data transform\n//First it will encrypt data, then it will compress the result\nIDataTransform combinedDataTransform = new CombinedDataTransform(encryptionDataTransform, compressionDataTransform);\n\n//Pass it to DataTransformSerializationProvider implementation\nISerializationProvider serializationProvider =\n    new DataTransformSerializationProvider(new UnityJsonSerializationProvider(),\n        combinedDataTransform);\n\n//Data transformation chains can be created indefinitely\nIDataTransform customDataTransform = new CustomDataTransform();\n\n//This will result in applying CustomDataTransform data transformations first,\n//then applying data transformations specified by combinedDataTransform instance\nIDataTransform multipleCombinedDataTransform =\n    new CombinedDataTransform(customDataTransform, combinedDataTransform);\n```\n## Sync/async API\nAll interfaces come in 3 variants:\n- Sync API\n- Async API\n- Both sync and async\n\nImplementations that depends on mentioned interfaces have same 3 variants, e.g. `FileStorage` for both sync and async API, `FileStorageSync` for sync API only and `FileStorageAsync` for async API only.\n\n# License\nThe software released under the terms of the [MIT license](./LICENSE.md).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdre0dru%2FLocalStorage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdre0dru%2FLocalStorage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdre0dru%2FLocalStorage/lists"}