Magic.IndexedDb 1.0.0

Magic.IndexedDb

This open source library provides an IndexedDb wrapper for C# and Blazor WebAssembly applications. It simplifies working with IndexedDb and makes it similar to using LINQ to SQL.

Thank you to nwestfall for his BlazorDB work, which was a fork of Blazor.IndexedDB.Framework by Reshiru

https://github.com/nwestfall/BlazorDB

NOTE: This code is still very young. I will be making updates for this code as I come across it. I will try my best to not depreciate or break syntax already in use. But please take note of any version updates before you use my code if you're updating it in the future. As I will not guarentee right now that I won't break your stuff if you download this version and then come back in a year and get the latest version.

Table of Contents

• Installation
• Usage
  • Setting up the project
  • Creating a class with Magic attributes
  • Using the DbManager
• Attributes
• Examples

Installation

1. Add the library to your project.
2. Add the following code to your Program.cs file:

/*
 * This is an example encryption key. You must make your own 128 bit or 256 bit 
 * key! Do not use this example encryption key that I've provided here as that's
 * incredibly unsafe!
 */
string EncryptionKey = "zQfTuWnZi8u7x!A%C*F-JaBdRlUkXp2l";

builder.Services.AddBlazorDB(options =>
{
    options.Name = DbNames.Client;
    options.Version = "1";
    options.EncryptionKey = EncryptionKey;
    options.StoreSchemas = SchemaHelper.GetAllSchemas("DatabaseName"); // builds entire database schema for you based on attributes
    options.DbMigrations = new List<DbMigration>
{
        /*
         * The DbMigration is not currently working or setup!
         * This is an example and idea I'm thinking about, but 
         * this will very likely be depreciated so do not use or rely
         * on any of this syntax right now. If you want to have 
         * your own migration knowledge. Write JavaScript on the front end 
         * that will check the indedDb version and then apply migration code 
         * on the front end if needed. But this is only needed for complex 
         * migration projects.
         */
    new DbMigration
    {
        FromVersion = "1.1",
        ToVersion = "2.2",
        Instructions = new List<DbMigrationInstruction>
        {
            new DbMigrationInstruction
            {
                Action = "renameStore",
                StoreName = "oldStore",
                Details = "newStore"
            }
        }
    }
};
});

3. Add the following scripts to the end of the body tag in your Index.html:

<script src="_content/Magic.IndexedDb/dexie.min.js"></script>
<script src="_content/Magic.IndexedDb/magicDB.js"></script>

4. Add the following to your _Import.razor:

@using Magic.IndexedDb
@inject IMagicDbFactory _MagicDb

Creating a class with Magic attributes

Define your class with the MagicTable attribute and the appropriate magic attributes for each property. For example:

[MagicTable("Person", "DatabaseName")]
public class Person
{
    [MagicPrimaryKey("id")]
    public int _Id { get; set; }

    [MagicIndex]
    public string Name { get; set; }

    [MagicIndex("Age")]
    public int _Age { get; set; }

    [MagicEncrypt]
    public string Secret { get; set; }

    [MagicNotMapped]
    public string SecretDecrypted { get; set; }
}

I highly suggest you always add the string parameters as that sets the IndexedDb column name. By default it'll use the C# class property name. But You should always have some very unique and static set string for the attribute. That way if/when you change the c# property names, class names, or anything, the schema will not care because the code has smart logic to differentiate the C# class property names and the IndexedDb column names that was set in your attribute. This way you can freely change any C# class properties without ever caring about needing to create migration code. You can additionally add or remove columns freely without issue.

Attributes

• MagicTable(string, string): Associates the class with a table in IndexedDb. The first parameter is the table name, and the second parameter is the database name.
• MagicPrimaryKey(string): Marks the property as the primary key. The parameter is the column name in IndexedDb.
• MagicIndex(string): Creates a searchable index for the property. The parameter is the column name in IndexedDb.
• MagicUniqueIndex(string): Creates a unique index for the property. The parameter is the column name in IndexedDb.
• MagicEncrypt: Encrypts the string property when it's stored in IndexedDb.
• MagicNotMapped: Excludes the property from being mapped to IndexedDb.

Using the DbManager

1. Get the DbManager for your database:

var manager = await _MagicDb.GetDbManager(DbNames.Client);

2. Perform operations with the DbManager, such as adding, updating, deleting, and querying data.

Here's a grid-style documentation for the methods:

"Where" Method MagicQuery syntax

These MagicQuery methods allow you to build complex queries similar to standard LINQ in C#. Remember to call the Execute method at the end of your MagicQuery to execute the query and retrieve the results.

Examples

To start using MagicIndexedDb, you need to create a DbManager instance for your specific database.

private List<Person> allPeople { get; set; } = new List<Person>();
private IEnumerable<Person> WhereExample { get; set; } = Enumerable.Empty<Person>();

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender)
    {
        try
        {
            var manager = await _MagicDb.GetDbManager(DbNames.Client);

            await manager.ClearTable<Person>();

                    var AllThePeeps = await manager.GetAll<Person>();
                    if (AllThePeeps.Count() < 1)
                    {
                        Person[] persons = new Person[] {
                    new Person { Name = "Zack", TestInt = 9, _Age = 45, GUIY = Guid.NewGuid(), Secret = "I buried treasure behind my house"},
                    new Person { Name = "Luna", TestInt = 9, _Age = 35, GUIY = Guid.NewGuid(), Secret = "Jerry is my husband and I had an affair with Bob."},
                    new Person { Name = "Jerry", TestInt = 9, _Age = 35, GUIY = Guid.NewGuid(), Secret = "My wife is amazing"},
                    new Person { Name = "Jon", TestInt = 9, _Age = 37, GUIY = Guid.NewGuid(), Secret = "I black mail Luna for money because I know her secret"},
                    new Person { Name = "Jack", TestInt = 9, _Age = 37, GUIY = Guid.NewGuid(), Secret = "I have a drug problem"},
                    new Person { Name = "Cathy", TestInt = 9, _Age = 22, GUIY = Guid.NewGuid(), Secret = "I got away with reading Bobs diary."},
                    new Person { Name = "Bob", TestInt = 3 , _Age = 69, GUIY = Guid.NewGuid(), Secret = "I caught Cathy reading my diary, but I'm too shy to confront her." },
                    new Person { Name = "Alex", TestInt = 3 , _Age = 80, GUIY = Guid.NewGuid(), Secret = "I'm naked! But nobody can know!" }
                    };

                        await manager.AddRange(persons);
                    }

                    var allPeopleDecrypted = await manager.GetAll<Person>();

                    foreach (Person person in allPeopleDecrypted)
                    {
                        person.SecretDecrypted = await manager.Decrypt(person.Secret);
                        allPeople.Add(person);
                    }

                    WhereExample = await manager.Where<Person>(x => x.Name.StartsWith("c", StringComparison.OrdinalIgnoreCase)
                    || x.Name.StartsWith("l", StringComparison.OrdinalIgnoreCase)
                    || x.Name.StartsWith("j", StringComparison.OrdinalIgnoreCase) && x._Age > 35
                    ).OrderBy(x => x._Id).Skip(1).Execute();

                    StateHasChanged();
        }
        catch (Exception ex)
        {
            // Handle exception
        }
    }
}

Adding Records

To add new records, use the AddRange method on the DbManager instance. This example adds new Person records to the database:

if (AllThePeeps.Count() < 1)
{
    Person[] persons = new Person[] {
        // ... (list of Person objects)
    };

    await manager.AddRange(persons);
}

Retrieving Records

To retrieve all records of a specific type, use the GetAll method on the DbManager instance. This example retrieves all Person records:

var allPeople = await manager.GetAll<Person>();

Decrypting Records

To decrypt a specific property of a record, use the Decrypt method on the DbManager instance. This example decrypts the Secret property of each Person:

foreach (Person person in allPeople)
{
    person.SecretDecrypted = await manager.Decrypt(person.Secret);
}

Querying Records

To query records based on specific conditions, use the Where method on the DbManager instance. You can chain additional LINQ methods, such as OrderBy, Skip, and Execute, to further refine your query. This example retrieves Person records that match certain criteria:

var whereExample = await manager.Where<Person>(x => x.Name.StartsWith("c", StringComparison.OrdinalIgnoreCase)
    || x.Name.StartsWith("l", StringComparison.OrdinalIgnoreCase)
    || x.Name.StartsWith("j", StringComparison.OrdinalIgnoreCase) && x._Age > 35
).OrderBy(x => x._Id).Skip(1).Execute();

In this example, the query returns Person records where the Name property starts with "c", "l", or "j" (case-insensitive), and the _Age property is greater than 35. The results are ordered by the _Id property and the first record is skipped.

These examples demonstrate the basics of using MagicIndexedDb in a Blazor WebAssembly application. You can also perform other operations, such as updating and deleting records, by using the appropriate methods provided by the DbManager.