@medyll/idae-query 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/index.d.ts

@@ -1,5 +1,5 @@
 export * from './operators/operators.js';
 export * from './path/pathResolver.js';
 export * from './query/query.js';
-export * from './resultset/resultset.js';
+export * from './resultSet/resultset.js';
 export * from './types.js';

package/dist/index.js

@@ -2,5 +2,5 @@
 export * from './operators/operators.js';
 export * from './path/pathResolver.js';
 export * from './query/query.js';
-export * from './resultset/resultset.js';
+export * from './resultSet/resultset.js';
 export * from './types.js';

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/query/query.d.ts

@@ -2,7 +2,7 @@ import type { Where } from '../types.js';
 export declare class Query<T extends object> {
     data: T[];
     constructor(data: T[]);
-    where(qy: Where<T>): import("../resultset/resultset.js").ResultSet<T>;
+    where(qy: Where<T>): any;
     private matchesQuery;
     private matchesField;
 }

package/dist/{resultset → resultSet}/Readme.md

@@ -1,39 +1,39 @@
-## ResultSet.ts
-
-This class `ResultSet` is used to manipulate and iterate over a set of data. The class is iterable, meaning it can be spread into an array or iterated over with a `for...of` loop.
-
-### Methods
-
- 
-
-#### setOptions<T>(options: OptionsType)
-
-- Action: Sets the options for the result set in one pass.
-- Arguments: An `OptionsType` object which can contain `sort`, `page`, and `groupBy` properties.
-  - `sort`: An object where the keys represent the properties to sort by, and the values represent the sort order ("asc" for ascending, "desc" for descending).
-  - `page`: An object with `size` and `number` properties, representing the number of items per page and the page number to retrieve, respectively.
-  - `groupBy`: A string or an array of strings, representing the field names to group by.
-- Return: The updated result set.
-
-
-#### sortBy(args: Record<string, "asc" | "desc">)
-
-- Action: Sorts the data in the result set based on the provided sorting criteria.
-- Arguments: An object where the keys represent the properties to sort by, and the values represent the sort order ("asc" for ascending, "desc" for descending).
-- Return: The sorted result set.
-
-#### getPage(size: number, page: number)
-
-- Action: Retrieves a specific page of data from the result set.
-- Arguments: The `size` parameter specifies the number of items per page, and the `page` parameter specifies the page number to retrieve.
-- Return: A new result set containing the specified page of data.
-
-#### groupBy(fieldName: string | string[], transform?: (value: any) => void)
-
-- Action: Groups the result set by the specified field name(s).
-- Arguments: The `fieldName` parameter can be a string or an array of strings, representing the field names to group by. The `transform` parameter is an optional transformation function to apply to each grouped value.
-- Return: An object representing the grouped result set.
-
-### Iterability
-
-The `ResultSet` class is iterable, meaning it can be spread into an array or iterated over with a `for...of` loop. This is achieved by implementing the `[Symbol.iterator]` method.
+## ResultSet.ts
+
+This class `ResultSet` is used to manipulate and iterate over a set of data. The class is iterable, meaning it can be spread into an array or iterated over with a `for...of` loop.
+
+### Methods
+
+ 
+
+#### setOptions<T>(options: OptionsType)
+
+- Action: Sets the options for the result set in one pass.
+- Arguments: An `OptionsType` object which can contain `sort`, `page`, and `groupBy` properties.
+  - `sort`: An object where the keys represent the properties to sort by, and the values represent the sort order ("asc" for ascending, "desc" for descending).
+  - `page`: An object with `size` and `number` properties, representing the number of items per page and the page number to retrieve, respectively.
+  - `groupBy`: A string or an array of strings, representing the field names to group by.
+- Return: The updated result set.
+
+
+#### sortBy(args: Record<string, "asc" | "desc">)
+
+- Action: Sorts the data in the result set based on the provided sorting criteria.
+- Arguments: An object where the keys represent the properties to sort by, and the values represent the sort order ("asc" for ascending, "desc" for descending).
+- Return: The sorted result set.
+
+#### getPage(size: number, page: number)
+
+- Action: Retrieves a specific page of data from the result set.
+- Arguments: The `size` parameter specifies the number of items per page, and the `page` parameter specifies the page number to retrieve.
+- Return: A new result set containing the specified page of data.
+
+#### groupBy(fieldName: string | string[], transform?: (value: any) => void)
+
+- Action: Groups the result set by the specified field name(s).
+- Arguments: The `fieldName` parameter can be a string or an array of strings, representing the field names to group by. The `transform` parameter is an optional transformation function to apply to each grouped value.
+- Return: An object representing the grouped result set.
+
+### Iterability
+
+The `ResultSet` class is iterable, meaning it can be spread into an array or iterated over with a `for...of` loop. This is achieved by implementing the `[Symbol.iterator]` method.

package/dist/{resultset → resultSet}/resultset.d.ts

@@ -1,11 +1,11 @@
-import { type DotPath } from "../path/pathResolver.js";
+import { type DotPath } from '../path/pathResolver.js';
 /**
  * Represents the options for a result set.
  * @template T - The type of the result set.
  */
 export type ResultsetOptions<T = any> = {
     /** Can receive a dot path for sorting. */
-    sort?: Record<DotPath<T>, "asc" | "desc">;
+    sort?: Record<DotPath<T>, 'asc' | 'desc'>;
     /** Specifies the property to group the result set by. */
     groupBy?: DotPath<T>;
     /** Specifies the page size of the result set. */
@@ -18,7 +18,7 @@ export type ResultsetOptions<T = any> = {
 export type ResultSet<T> = T[] & {
     setOptions: (options: ResultsetOptions) => ResultSet<T>;
     /** Accepts a dot path */
-    sortBy: (args: Record<string, "asc" | "desc">) => ResultSet<T>;
+    sortBy: (args: Record<string, 'asc' | 'desc'>) => ResultSet<T>;
     /** Accepts a dot path as fieldName */
     groupBy: (fieldName: string | string[], 
     /** Transformer function to generate the grouped key */

package/dist/{resultset → resultSet}/resultset.js

@@ -1,4 +1,4 @@
-import { dotPath } from "../path/pathResolver.js";
+import { dotPath } from '../path/pathResolver.js';
 /**
  * Generates a ResultSet based on the provided data array and defines additional properties like setOptions, sortBy, groupBy, and getPage for customization and manipulation.
  *
@@ -19,7 +19,7 @@ export function getResultset(data) {
                 return this;
             },
             enumerable: false,
-            configurable: true,
+            configurable: true
         },
         sortBy: {
             value: function (args) {
@@ -31,7 +31,7 @@ export function getResultset(data) {
                     while (i < keys.length && result === 0) {
                         let value = keys[i];
                         result =
-                            values[i] === "asc"
+                            values[i] === 'asc'
                                 ? Number(dotPath(a, value)) - Number(dotPath(b, value))
                                 : Number(dotPath(b, value)) - Number(dotPath(a, value));
                         i++;
@@ -42,13 +42,13 @@ export function getResultset(data) {
                 return this;
             },
             enumerable: false,
-            configurable: true,
+            configurable: true
         },
         groupBy: {
             value: function (fieldName, transform) {
-                const finalFieldName = typeof fieldName === "string" ? [fieldName] : fieldName;
+                const finalFieldName = typeof fieldName === 'string' ? [fieldName] : fieldName;
                 return this.reduce((acc, curr) => {
-                    let key = "";
+                    let key = '';
                     for (let i = 0; i < finalFieldName.length; i++) {
                         key += dotPath(curr, finalFieldName[i]);
                     }
@@ -60,7 +60,7 @@ export function getResultset(data) {
                 }, {});
             },
             enumerable: false,
-            configurable: true,
+            configurable: true
         },
         getPage: {
             value: function (page, size) {
@@ -69,8 +69,8 @@ export function getResultset(data) {
                 return dta;
             },
             enumerable: false,
-            configurable: true,
-        },
+            configurable: true
+        }
     });
     return data;
 }

package/package.json

@@ -1,12 +1,13 @@
 {
 	"name": "@medyll/idae-query",
 	"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",
@@ -26,9 +27,10 @@
 		"!dist/**/*.spec.*"
 	],
 	"peerDependencies": {
-		"svelte": "^4.0.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,7 +43,7 @@
 		"prettier": "^3.1.1",
 		"prettier-plugin-svelte": "^3.1.2",
 		"publint": "^0.1.9",
-		"svelte": "^5.0.0-next.181",
+		"svelte": "^5.0.0-next.183",
 		"svelte-check": "^3.6.0",
 		"tslib": "^2.4.1",
 		"typescript": "^5.0.0",
@@ -52,4 +54,4 @@
 	"svelte": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"type": "module"
-}
+}