@medyll/idae-idbql 0.0.1 → 0.1.0

package/README.md

@@ -1,58 +1,184 @@
-# create-svelte
+# @medyll/idae-idbql
 
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
+A powerful and flexible IndexedDB query library for TypeScript and JavaScript applications.
 
-Read more about creating a library [in the docs](https://kit.svelte.dev/docs/packaging).
+## Features
 
-## Creating a project
+- MongoDB-like query interface for IndexedDB
+- Strong TypeScript support with full type inference
+- Reactive state management for real-time UI updates
+- Support for complex CRUD operations and advanced querying
+- Flexible data modeling with automatic schema creation
+- Built-in indexing and optimization features
+- Easy integration with front-end frameworks, especially Svelte
+- Robust error handling and logging
+- Versioning and database migration support
+- Support for svelte 5 state
 
-If you're seeing this, you've probably already done this step. Congrats!
+## Installation
 
 ```bash
-# create a new project in the current directory
-npm create svelte@latest
+npm install @medyll/idae-idbql
+```
 
-# create a new project in my-app
-npm create svelte@latest my-app
+## Quick Start
+
+```typescript
+import { createIdbqDb } from '@medyll/idae-idbql';
+
+// Define your data model
+const exampleModel = {
+  messages: {
+    keyPath: "++id, chatId, created_at",
+    ts: {} as ChatMessage,
+  },
+  chat: {
+    keyPath: "&chatId, created_at, dateLastMessage",
+    ts: {} as Chat,
+    template: {},
+  },
+};
+
+// Create a database instance
+const idbqStore = createIdbqDb(exampleModel, 1);
+const { idbql, idbqlState, idbDatabase, idbqModel } = idbqStore.create("myDatabase");
+
+// Perform database operations
+async function fetchMessages() {
+  const messages = await idbql.messages.where({ chatId: "123" }).toArray();
+  console.log(messages);
+}
+
+fetchMessages();
 ```
 
-## Developing
+## API Reference
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+### createIdbqDb(model, version)
 
-```bash
-npm run dev
+Creates an IndexedDB database instance with the specified model and version.
+
+### idbql
+
+The main interface for database operations. Provides methods for each collection defined in your model.
+
+### idbqlState
+
+A reactive state object that reflects the current state of your database.
+
+### idbDatabase
+
+Provides low-level access to the IndexedDB instance.
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+### idbqModel
+
+Contains the database model definition.
+
+## Query Operations
+
+```typescript
+// Add a new item
+await idbql.messages.add({ chatId: "123", content: "Hello" });
+
+// Update an item
+await idbql.messages.put({ id: 1, content: "Updated message" });
+
+// Delete an item
+await idbql.messages.delete(1);
+
+// Query items
+const recentMessages = await idbql.messages
+  .where({ created_at: { gt: new Date(Date.now() - 86400000) } })
+  .toArray();
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+## Transactions
 
-## Building
+idbql supports complex transactions across multiple object stores:
 
-To build your library:
+```typescript
+const result = await idbql.transaction(
+  ["users", "posts"],
+  "readwrite",
+  async (tx) => {
+    const userStore = tx.objectStore("users");
+    const postStore = tx.objectStore("posts");
 
-```bash
-npm run package
+    const userId = await userStore.add({ name: "Alice", email: "alice@example.com" });
+    const postId = await postStore.add({ userId, title: "Alice's First Post", content: "Hello, World!" });
+
+    return { userId, postId };
+  }
+);
 ```
 
-To create a production version of your showcase app:
+## Reactive State Management
 
-```bash
-npm run build
+```typescript
+import { derived } from 'svelte/store';
+
+const activeUsers = $derived(idbqlState.users.where({ isActive: true }));
 ```
 
-You can preview the production build with `npm run preview`.
+## Integration with Svelte
 
-> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
+```svelte
+<script>
+import { derived } from 'svelte/store';
+import { idbqlState } from './store';
 
-## Publishing
+const messages = $derived(idbqlState.messages.where({ chatId: "123" }));
+</script>
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+{#each $messages as message}
+  <p>{message.content}</p>
+{/each}
+```
 
-To publish your library to [npm](https://www.npmjs.com):
+## Versioning and Migrations
+
+```typescript
+const idbqStore = createIdbqDb(myModel, 2);
+const { idbDatabase } = idbqStore.create("myDb", {
+  upgrade(oldVersion, newVersion, transaction) {
+    if (oldVersion < 2) {
+      const userStore = transaction.objectStore("users");
+      userStore.createIndex("emailIndex", "email", { unique: true });
+    }
+  },
+});
+```
 
-```bash
-npm publish
+## Error Handling
+
+```typescript
+try {
+  await idbql.users.add({ username: "existing_user" });
+} catch (error) {
+  if (error instanceof UniqueConstraintError) {
+    console.error("Username already exists");
+  } else {
+    console.error("An unexpected error occurred", error);
+  }
+}
 ```
+
+## Performance Tips
+
+- Use appropriate indexes
+- Limit result sets with `.limit(n)`
+- Use `.count()` instead of `.toArray().length`
+- Optimize queries to use indexes effectively
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Support
+
+If you encounter any issues or have questions, please file an issue on the GitHub repository.
+ 

package/dist/collection/collection.d.ts

@@ -1,4 +1,4 @@
-import { type Where, type ResultsetOptions, type ResultSet } from "@medyll/idae-query";
+import { type Where, type ResultsetOptions, type ResultSet } from '@medyll/idae-query';
 export declare class CollectionCore<T = any> {
     protected _store: string;
     private version?;

package/dist/collection/collection.js

@@ -1,7 +1,7 @@
 /* path:  src\lib\scripts\collection\collection.ts */
-import { Query, getResultset } from "@medyll/idae-query";
-import {} from "@medyll/idae-query";
-import { idbqlEvent } from "../state/idbqlEvent.svelte.js";
+import { Query, getResultset } from '@medyll/idae-query';
+import {} from '@medyll/idae-query';
+import { idbqlEvent } from '../state/idbqlEvent.svelte.js';
 export class CollectionCore {
     _store;
     version;
@@ -12,7 +12,7 @@ export class CollectionCore {
         this._store = store;
         this.version = args.version;
         this.dbName = args.dbName;
-        this.keyPath = keyPath.split(",")[0].replace(/[\s+]/g, "").replace(/&/, "");
+        this.keyPath = keyPath.split(',')[0].replace(/[\s+]/g, '').replace(/&/, '');
     }
     get name() {
         return this._store;
@@ -30,7 +30,7 @@ export class CollectionCore {
         if (!db.objectStoreNames.contains(this._store)) {
             throw new Error(`Collection ${this._store} not found`);
         }
-        return db.transaction(this._store, "readwrite").objectStore(this._store);
+        return db.transaction(this._store, 'readwrite').objectStore(this._store);
     }
     /**
      * Retrieves the data from the collection based on the provided query.
@@ -53,7 +53,7 @@ export class CollectionCore {
             const storeObj = await this.getCollection();
             const get = storeObj.get(value);
             get.onsuccess = () => resolve(get.result);
-            get.onerror = () => reject("not found");
+            get.onerror = () => reject('not found');
         });
     }
     getAll() {
@@ -64,7 +64,7 @@ export class CollectionCore {
                 resolve(getAll.result);
             };
             getAll.onerror = function () {
-                reject("not found");
+                reject('not found');
             };
         });
     }
@@ -73,7 +73,7 @@ export class CollectionCore {
         return this.put({
             [this.keyPath]: keyPathValue,
             ...dta,
-            ...data,
+            ...data
         });
     }
     async updateWhere(where, data) {
@@ -84,7 +84,7 @@ export class CollectionCore {
                         const newData = {
                             [this.keyPath]: dta[this.keyPath],
                             ...dta,
-                            ...data,
+                            ...data
                         };
                         return this.put(newData);
                     }
@@ -108,7 +108,7 @@ export class CollectionCore {
                 resolve(updatedData);
             };
             put.onerror = function () {
-                reject("data not put");
+                reject('data not put');
             };
         });
     }
@@ -132,10 +132,10 @@ export class CollectionCore {
             const storeObj = await this.getCollection();
             let objectStoreRequest = storeObj.delete(keyPathValue);
             objectStoreRequest.onsuccess = () => {
-                idbqlEvent.registerEvent("delete", {
+                idbqlEvent.registerEvent('delete', {
                     collection: this._store,
                     data: keyPathValue,
-                    keyPath: this.keyPath,
+                    keyPath: this.keyPath
                 });
                 resolve(true);
             };
@@ -170,15 +170,8 @@ function createIDBStoreProxy(store) {
             return new Proxy(instance, {
                 get(target, prop, receiver) {
                     const origMethod = target[prop];
-                    if (typeof origMethod === "function" &&
-                        [
-                            "update",
-                            "updateWhere",
-                            "put",
-                            "add",
-                            "delete",
-                            "deleteWhere",
-                        ].includes(String(prop))) {
+                    if (typeof origMethod === 'function' &&
+                        ['update', 'updateWhere', 'put', 'add', 'delete', 'deleteWhere'].includes(String(prop))) {
                         return function (...args) {
                             return new Promise(async (resolve, reject) => {
                                 origMethod
@@ -187,7 +180,7 @@ function createIDBStoreProxy(store) {
                                     idbqlEvent.registerEvent(prop, {
                                         collection: instance._store,
                                         data: res,
-                                        keyPath: instance.keyPath,
+                                        keyPath: instance.keyPath
                                     });
                                     resolve(res);
                                 })
@@ -199,8 +192,8 @@ function createIDBStoreProxy(store) {
                         };
                     }
                     return Reflect.get(target, prop, receiver);
-                },
+                }
             });
-        },
+        }
     });
 }

package/dist/idbqlCore/idbqlCore.d.ts

@@ -1,5 +1,5 @@
-import { CollectionCore } from "../collection/collection.js";
-import { type StateCollectionDyn } from "../state/idbstate.svelte.js";
+import { CollectionCore } from '../collection/collection.js';
+import { type StateCollectionDyn } from '../state/idbstate.svelte.js';
 export declare enum enumPrimitive {
     id = "id",
     any = "any",
@@ -23,7 +23,7 @@ type CombineElements<T extends string, U extends string = T> = T extends any ? T
 type CombinedArgs = CombineElements<TplProperties>;
 type IdbObjectify<T extends string> = `array-of-${T}` | `object-${T}`;
 export type TplCollectionFields = Record<string, string>;
-export type TplFieldPrimitive<T = {}> = keyof typeof enumPrimitive | `text-${"tiny" | "short" | "medium" | "long" | "area"}` | `${string}.${string}` | `fk-${string}.${string}`;
+export type TplFieldPrimitive<T = {}> = keyof typeof enumPrimitive | `text-${'tiny' | 'short' | 'medium' | 'long' | 'area'}` | `${string}.${string}` | `fk-${string}.${string}`;
 export type TplObjectFieldPrimitive = IdbObjectify<TplFieldPrimitive>;
 export type TplFieldFk = `fk-${string}.${string}`;
 export type TplFkObject = IdbObjectify<TplFieldFk>;
@@ -44,8 +44,8 @@ export type IdbqModel<T = Record<string, Record<string, any>>> = {
     readonly [K in keyof T]: CollectionModel<T[K]>;
 };
 export type TplCollectionName<T = TplCollectionFields> = keyof IdbqModel<T>;
-export type Tpl<T = TplCollectionFields> = CollectionModel<T>["template"];
-export type TplFields<T = TplCollectionFields> = CollectionModel<T>["template"]["fields"];
+export type Tpl<T = TplCollectionFields> = CollectionModel<T>['template'];
+export type TplFields<T = TplCollectionFields> = CollectionModel<T>['template']['fields'];
 export type CollectionModel<T = TplCollectionFields> = {
     keyPath: string | any;
     /** @deprecated use ts instead */
@@ -53,7 +53,7 @@ export type CollectionModel<T = TplCollectionFields> = {
     ts: any;
     template: {
         index: string;
-        presentation: CombineElements<keyof CollectionModel<T>["ts"]>;
+        presentation: CombineElements<keyof CollectionModel<T>['ts']>;
         fields: {
             [K in keyof T]: TplFieldRules;
         };
@@ -67,10 +67,10 @@ export type CollectionModel<T = TplCollectionFields> = {
     };
 };
 type ReadonlyCollections<T extends IdbqModel> = {
-    [K in keyof T]: CollectionCore<T[K]["ts"]>;
+    [K in keyof T]: CollectionCore<T[K]['ts']>;
 };
 type StateCollections<T extends IdbqModel> = {
-    [K in keyof T]: StateCollectionDyn<T[K]["ts"]>;
+    [K in keyof T]: StateCollectionDyn<T[K]['ts']>;
 };
 /**
  * Represents the IndexedDB wrapper for managing database operations.

package/dist/idbqlCore/idbqlCore.js

@@ -1,7 +1,7 @@
 /* src\lib\scripts\idbqlCore\idbqlCore.ts */
-import { Collection, CollectionCore } from "../collection/collection.js";
-import { createIdbqlState, } from "../state/idbstate.svelte.js";
-import { Schema } from "./idbqlSchema.js";
+import { Collection, CollectionCore } from '../collection/collection.js';
+import { createIdbqlState } from '../state/idbstate.svelte.js';
+import { Schema } from './idbqlSchema.js';
 export var enumPrimitive;
 (function (enumPrimitive) {
     enumPrimitive["id"] = "id";
@@ -23,7 +23,7 @@ export var TplProperties;
     TplProperties["readonly"] = "readonly";
     TplProperties["required"] = "required";
 })(TplProperties || (TplProperties = {}));
-const a = "object-any (readonly private)";
+const a = 'object-any (readonly private)';
 /**
  * Represents the IndexedDB wrapper for managing database operations.
  * @template T - The type of data stored in the IndexedDB.
@@ -45,13 +45,13 @@ export class IdbqlIndexedCore {
         const stores = {};
         Object.keys(idbqModel).forEach((modelName) => {
             const modelInfo = idbqModel[modelName];
-            stores[modelName] = modelInfo.keyPath || "";
+            stores[modelName] = modelInfo.keyPath || '';
             Object.defineProperty(this, modelName, {
                 // @ts-ignore
                 value: undefined,
                 writable: true,
                 enumerable: true,
-                configurable: true,
+                configurable: true
             });
         });
         this.stores(stores);
@@ -68,7 +68,7 @@ export class IdbqlIndexedCore {
      * @returns {object} - An object with a `stores` method to define the object stores.
      */
     async stores(args) {
-        if (typeof indexedDB !== "undefined") {
+        if (typeof indexedDB !== 'undefined') {
             return new Promise((resolve, reject) => {
                 this.#schema = args;
                 const dbConnection = indexedDB.open(this.databaseName, this.dbVersion);
@@ -98,7 +98,7 @@ export class IdbqlIndexedCore {
     }
     async transaction(storeNames, mode, callback) {
         if (!this.idbDatabase) {
-            throw new Error("Database not initialized");
+            throw new Error('Database not initialized');
         }
         return new Promise((resolve, reject) => {
             const tx = this.idbDatabase.transaction(storeNames, mode);
@@ -120,11 +120,11 @@ export class IdbqlIndexedCore {
                 // @ts-ignore
                 value: new Collection(storeName, this.#schema[storeName], {
                     dbName: this.databaseName,
-                    version, // @ts-ignore
+                    version // @ts-ignore
                 }),
                 writable: true,
                 enumerable: true,
-                configurable: true,
+                configurable: true
             });
         });
     }
@@ -147,9 +147,9 @@ export const createIdbqDb = (model, version) => {
                 idbDatabase: idb_,
                 idbql: idb_,
                 idbqlState: createIdbqlState(idb_).state,
-                idbqModel: model,
+                idbqModel: model
             };
-        },
+        }
     };
 };
 // main export is here ?

package/dist/idbqlCore/idbqlSchema.js

@@ -32,13 +32,9 @@ export class Schema {
     async createSchema(db, storeListFields) {
         const results = [];
         for (const [storeName, storeConfig] of Object.entries(storeListFields)) {
-            const fields = storeConfig.split(",").map((field) => field.trim());
-            const incrementField = fields
-                .find((field) => field.startsWith("++"))
-                ?.replace("++", "");
-            const declaredIndex = fields
-                .find((field) => field.startsWith("&"))
-                ?.replace("&", "");
+            const fields = storeConfig.split(',').map((field) => field.trim());
+            const incrementField = fields.find((field) => field.startsWith('++'))?.replace('++', '');
+            const declaredIndex = fields.find((field) => field.startsWith('&'))?.replace('&', '');
             const keyPath = incrementField || declaredIndex || fields[0];
             const increment = Boolean(incrementField);
             const store = this.createStore(db, storeName, keyPath, increment);
@@ -57,7 +53,7 @@ export class Schema {
      * @returns The cleaned index name.
      */
     cleanIndexName(indexName) {
-        return indexName.replace(/[&+]/g, "").trim();
+        return indexName.replace(/[&+]/g, '').trim();
     }
     /**
      * Creates an index in the object store.

package/dist/path/pathResolver.d.ts

@@ -1,6 +1,6 @@
 export type DotPath<T> = T extends object ? {
-    [K in keyof T]: T[K] extends null | undefined ? K & string : `${K & string}${"" extends DotPath<T[K]> ? "" : "."}${DotPath<T[K]>}`;
-}[keyof T] : "";
+    [K in keyof T]: T[K] extends null | undefined ? K & string : `${K & string}${'' extends DotPath<T[K]> ? '' : '.'}${DotPath<T[K]>}`;
+}[keyof T] : '';
 /**
  * Resolves a dot path on an object and returns the value at that path.
  * If the path does not exist, it returns the defaultValue.

package/dist/path/pathResolver.js

@@ -9,6 +9,5 @@
  * @returns The value at the specified path, or the defaultValue if the path does not exist.
  */
 export function dotPath(object, path, defaultValue) {
-    return (path.split(".").reduce((r, s) => (r ? r[s] : defaultValue), object) ??
-        defaultValue);
+    return (path.split('.').reduce((r, s) => (r ? r[s] : defaultValue), object) ?? defaultValue);
 }

package/dist/state/idbqlEvent.svelte.d.ts

@@ -1,4 +1,4 @@
-type EventType = "add" | "put" | "update" | "updateWhere" | "delete" | "deleteWhere" | "set";
+type EventType = 'add' | 'put' | 'update' | 'updateWhere' | 'delete' | 'deleteWhere' | 'set';
 interface EventData<T = any> {
     collection: string;
     data: T;

package/dist/state/idbqlEvent.svelte.js

@@ -13,24 +13,24 @@ class IdbqlStateEvent {
             this.#dataState[collection] = [];
         }
         switch (event) {
-            case "set":
+            case 'set':
                 if (data) {
                     this.#dataState[collection] = Array.isArray(data) ? data : [data];
                 }
                 break;
-            case "add":
+            case 'add':
                 if (data) {
                     this.#dataState[collection].push(data);
                 }
                 break;
-            case "put":
-            case "update":
+            case 'put':
+            case 'update':
                 if (data && keyPath) {
                     const index = this.#dataState[collection].findIndex((item) => item[keyPath] === data[keyPath]);
                     if (index !== -1) {
                         this.#dataState[collection][index] = {
                             ...this.#dataState[collection][index],
-                            ...data,
+                            ...data
                         };
                     }
                     else {
@@ -38,20 +38,20 @@ class IdbqlStateEvent {
                     }
                 }
                 break;
-            case "updateWhere":
-                if (data && typeof data === "object") {
+            case 'updateWhere':
+                if (data && typeof data === 'object') {
                     this.#dataState[collection] = this.#dataState[collection].map((item) => Object.entries(data).every(([key, value]) => item[key] === value)
                         ? { ...item, ...data }
                         : item);
                 }
                 break;
-            case "delete":
+            case 'delete':
                 if (data && keyPath) {
                     this.#dataState[collection] = this.#dataState[collection].filter((item) => item[keyPath] !== data[keyPath]);
                 }
                 break;
-            case "deleteWhere":
-                if (data && typeof data === "object") {
+            case 'deleteWhere':
+                if (data && typeof data === 'object') {
                     this.#dataState[collection] = this.#dataState[collection].filter((item) => !Object.entries(data).every(([key, value]) => item[key] === value));
                 }
                 break;

package/dist/state/idbstate.svelte.d.ts

@@ -1,5 +1,5 @@
-import type { IdbqlIndexedCore } from "../idbqlCore/idbqlCore.js";
-import { type Where, type ResultSet, type ResultsetOptions } from "@medyll/idae-query";
+import type { IdbqlIndexedCore } from '../idbqlCore/idbqlCore.js';
+import { type Where, type ResultSet, type ResultsetOptions } from '@medyll/idae-query';
 /**
  * Main entry point.
  * Creates a state object with indexedDB synchronization.
@@ -26,7 +26,7 @@ export declare class StateCollectionDyn<T> {
     get collectionState(): any;
     private testIdbql;
     private feed;
-    where(qy: Where<T>, options?: ResultsetOptions): ResultSet<T>;
+    where(qy: Where<T>, options?: ResultsetOptions): any;
     update(keyPathValue: string | number, data: Partial<T>): void;
     get(value: any, pathKey?: string): T[];
     getOne(value: any, pathKey?: string): T;

package/dist/state/idbstate.svelte.js

@@ -1,6 +1,6 @@
-import { idbqlEvent } from "./idbqlEvent.svelte.js";
+import { idbqlEvent } from './idbqlEvent.svelte.js';
 //
-import { Operators, getResultset, } from "@medyll/idae-query";
+import { Operators, getResultset } from '@medyll/idae-query';
 //
 /**
  * Main entry point.
@@ -34,7 +34,7 @@ export const createIdbqlState = (idbBase) => {
             return collections;
         },
         onCollection: addCollection,
-        addCollection: addCollection,
+        addCollection: addCollection
     };
 };
 /**
@@ -81,10 +81,10 @@ export class StateCollectionDyn {
             this.idbBase[this.collectionName].update(keyPathValue, data);
         }
     }
-    get(value, pathKey = "id") {
+    get(value, pathKey = 'id') {
         return this.collectionState.filter((d) => d[pathKey] === value);
     }
-    getOne(value, pathKey = "id") {
+    getOne(value, pathKey = 'id') {
         return this.collectionState.filter((d) => d[pathKey] === value)?.[0];
     }
     getAll() {

package/package.json

@@ -1,12 +1,13 @@
 {
 	"name": "@medyll/idae-idbql",
 	"scope": "@medyll",
-	"version": "0.0.1",
+	"version": "0.1.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run package",
 		"preview": "vite preview",
 		"package": "svelte-kit sync && svelte-package && publint",
+		"package:watch": "svelte-kit sync && svelte-package --watch",
 		"prepublishOnly": "npm run package",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
@@ -23,9 +24,10 @@
 		"!dist/**/*.spec.*"
 	],
 	"peerDependencies": {
-		"svelte": "^5.0.0-next.0"
+		"svelte": "^5.0.0-next.1"
 	},
 	"devDependencies": {
+		"@medyll/idae-prettier-config": "^1.0.0",
 		"@sveltejs/adapter-auto": "^3.0.0",
 		"@sveltejs/kit": "^2.0.0",
 		"@sveltejs/package": "^2.0.0",
@@ -41,6 +43,6 @@
 	"types": "./dist/index.d.ts",
 	"type": "module",
 	"dependencies": {
-		"@medyll/idae-query": "^0.0.1"
+		"@medyll/idae-query": "^0.1.0"
 	}
-}
+}