Scott.Idem/OSIT-AE-App-Svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Reorganize documentation files

Browse Source 
- Centralize project-wide documentation into a new /documentation directory.
- Remove old, deprecated README guideline files.
- Create a comprehensive AETHER_API_OBJECTS.md file detailing all API data models.
This commit is contained in:
Scott Idem
2025-11-20 14:26:30 -05:00
parent 65b793f663
commit 064942c647
9 changed files with 2274 additions and 390 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2274
documentation/AETHER_API_OBJECTS.md Normal file
View File

File diff suppressed because it is too large Load Diff

142
documentation/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,142 @@
# Aether Project Architecture
This document outlines the overall architecture and key technologies used in the Aether SvelteKit frontend project.
## 1. Project Overview
The Aether project is a Svelte and SvelteKit based application, utilizing Tailwind CSS and Skeleton for styling and UI elements. It serves as the frontend UI/UX for the Aether system, which interacts with a Python FastAPI backend.
## 2. Core Technologies
- **Frontend Framework:** Svelte 5 and SvelteKit v2
- **Routing:** SvelteKit's file-system based routing.
- **Styling:** Tailwind CSS v4
- **UI Component Libraries:**
- Skeleton (Design System, Tailwind Components, Functional Components - being phased out due to conflicts with Tailwind CSS v4)
- Flowbite (Tailwind Components)
- Custom Components (a growing library of `ae_comp__*` and `element_*` components)
- **Text/Code Editors:**
- CodeMirror 6.x (primary text and code editor, planned for rich text editing)
- Edra (TipTap based Rich Text Editor)
- **Note:** ShadEditor TipTap is present but marked for removal, with CodeMirror being the preferred solution for all text editing needs.
- **Icons:** Lucide Icons (SVG Icons)
- **Markdown Parsing:** `marked` library
- **State Management:** Svelte stores, potentially with `liveQuery` from Dexie for reactive IndexedDB interactions.
## 3. Module Structure
The Aether project is organized into several modules, categorized as Core, Extended, and Custom.
### 3.1. Official Modules
#### Core Modules
These are foundational modules essential for the application's basic functionality.
- **Accounts:** Minimal implementation.
- **Files:** Manages hosted files.
- **People:** Minimal implementation for person records.
- **Sites:** Minimal implementation for site configurations.
- **Users:** Minimal implementation for user management.
#### Extended Modules
These modules provide additional features and functionalities.
- **Archives:** Minimal implementation.
- **Events:** Includes features for Badges and Presentation Management.
- **Posts:** Minimal implementation.
- **Journals:** Manages journal entries.
#### Custom Modules
These modules are tailored for specific client needs.
- **IDAA:** Includes Archives, Bulletin Board (BB), and Recovery Meetings functionalities.
## 4. Data Storage Mechanisms
### 4.1. Local Storage
Used for client-side persistence of various application states and configurations.
- `api`: API-related settings.
- `app`: Global application settings.
- `core`: Settings and data specific to core modules.
- `<module>`: Settings and data specific to extended modules.
- `<custom>`: Settings and data specific to custom modules.
### 4.2. IndexedDB (Dexie.js)
Used for more structured client-side data storage, often for caching and offline capabilities.
- `ae_core_db`: Core database instance.
- `<module>`: Module-specific database instances.
- `<custom>`: Custom module-specific database instances (none currently defined).
## 5. Data Sorting
Standardized sorting orders are applied across various data lists.
- **Default/General:** `group > priority > sort > updated_on/created_on`
- **Specific (e.g., Events):** `type > start_date/time > code or name`
## 6. Object Properties and Fields
A set of standardized field names and types are used across Aether objects.
### 6.1. Core Standard Fields
These fields are expected to be present in most Aether objects.
- `id`: Primary key for an object (internal use, often a UUID).
- `id_random`: Randomly generated ID for an object (often used for external exposure or URL parameters).
- `<object_type>_id_random`: Specific random ID for an object (e.g., `person_id_random`).
- `code`: Short, unique identifier.
- `name`: Display name.
- `enable`: Boolean for active/inactive status.
- `hide`: Boolean for visibility.
- `priority`: Numeric value for ordering.
- `sort`: Numeric value for ordering.
- `group`: Categorization string.
- `notes`: General notes/comments.
- `created_on`: Timestamp of creation.
- `updated_on`: Timestamp of last update.
### 6.2. Special Use Fields
Fields with specific purposes or conditional usage.
- `for_type`: Indicates the type of object this object is linked to.
- `for_id`: The ID of the object this object is linked to.
- `archive_on`: Timestamp for archiving.
- `passcode`: Password or access code.
- `external_id`: ID from an external system.
### 6.3. Configuration and JSON Fields
Fields designed to store JSON data.
- `cfg_json`: Configuration data in JSON format.
- `data_json`: General data in JSON format.
- `linked_li_json`: List of linked items in JSON format.
### 6.4. Special Generated Fields (Client-side)
Fields generated on the client-side, primarily for sorting or UI logic.
- `tmp_sort_1`
- `tmp_sort_2`
- `tmp_sort_3`
### 6.5. Future Standard Fields
A list of potential future standard fields, often prefixed with `obj_`. These are currently conceptual and not yet fully integrated.
- `obj_id`, `obj_ext_uid`, `obj_ext_id`, `obj_import_id`, `obj_code`, `obj_account_id`, `obj_passcode`, `obj_type`, `obj_type_ver_id`, `obj_name`, `obj_summary`, `obj_outline`, `obj_description`, `obj_enable`, `obj_enable_on`, `obj_archive_on`, `obj_hide`, `obj_priority`, `obj_sort`, `obj_group`, `obj_cfg_json`, `obj_notes`, `obj_created_on`, `obj_updated_on`.
## 7. IndexedDB LiveQuery Usage
- `lq__xyz_obj`: Used for general read-only access to liveQuery results.
- `lqw__xyz_obj`: Used for forms and binding values, representing a writable snapshot of liveQuery results.
- **Note:** Care must be taken when binding to `lqw__xyz_obj` to manage updates and potential conflicts with the underlying liveQuery.

148
documentation/COMPONENTS.md Normal file
View File

@@ -0,0 +1,148 @@
# Aether Project Components
This document details the various UI components used throughout the Aether SvelteKit frontend project, categorized by their scope and functionality.
## 1. Aether Components (UI/UX)
### 1.1. System Components
These components are part of the core application shell and provide global functionalities.
- **`header`**: Application-wide header.
- **`main/module`s**: Main content area for modules.
- **`footer`**: Application-wide footer.
- **`app`**: Provides global application functionalities such as:
- Refresh application state.
- Clear IndexedDB.
- Clear local storage (settings).
- Toggle iframe visibility (also updates URL parameter).
- Copy current URL.
- Generate and display QR codes.
- **`menu`**: Various menus for different purposes:
- **`mode`**: Edit mode toggle, more options (all or details).
- **`access_type`**: Passcode input, clear access.
- **`user`**: Sign in/out, reset password, email link, change username and email.
- **`theme`**: Mode (light/dark), name (theme list).
- **`debug`**: Developer-facing tools:
- Toggle debug mode (also updates URL parameter).
- Show core and module storages.
- Manually set initial timestamp.
- **`scroll_to`**: Navigation controls for scrolling:
- Scroll to top of the page.
- Scroll page up.
- Scroll page down.
- Scroll to bottom of the page.
### 1.2. Core Components
These are reusable components that provide common functionalities across different modules.
- **`copy_btn`**: A button to copy content to the clipboard.
- Properties: `clipboard`, `bind:value`, `btn_text`, `btn_html`.
- **`txt_editor`**: A basic text area editor.
- **`md_editor`**: Markdown editor.
- Uses CodeMirror (planned for rich text editing).
- **Note:** ShadEditor TipTap is present but marked for removal. ShadCN components are also being phased out in favor of CodeMirror for text editing.
- **`html_editor`**: HTML editor.
- **`media_player`**: Component for playing media files.
- Properties: `hosted_file`, `archive_content`, `media_player`.
- Bindings: `bind:host_id`, `bind:media_type`.
- Status: `stopped`, `paused`, `playing`.
- **`hosted_file_li`**: Manages a list of hosted files, making them available for selection.
- **`hosted_file_link_to`**: Lists links per object, with bindings to add/remove links.
- **`upload_to_host`**: Component for uploading files to the host.
- Handles multiple files.
- Properties: `link_type`, `link_id`, `inner fragment` (label html).
- Bindings: `bind:trigger`, `bind:show_spinner`, `bind:show_percent`.
- Status: `started`, `uploading`, `finished`.
- **`upload_file_tbl`**: Table for uploaded files, includes checks for duplicate file hashes and removal from the list.
- **`download_from_host`**: Component for downloading files from the host.
- Bindings: `bind:host_file_id`, `bind:filename`, `bind:file_ext`.
- Properties: `btn inner fragment`.
- Bindings: `bind:trigger`, `bind:show_spinner`, `bind:show_percent`.
- Status: `started`, `downloading`, `finished`.
- **`data_store`**: Component for interacting with data stores.
- **`ae_crud`**: Generic CRUD (Create, Read, Update, Delete) component.
- **Note:** Needs simplification.
- Properties: `obj`, `prop`, `current_value`.
- Bindings: `bind:value`, `bind:trigger`, `inner fragment`.
- **`ae_obj_prop_val`**: A wrapper for a function to manage object property values.
- Bindings: `bind:obj_type`, `bind:obj_id`, `bind:obj_prop`, `bind:obj_value`, `bind:obj_new_value`, `bind:trigger`, `bind:show_spinner`, `bind:show_percent`.
- Status: `status`, `result`.
- **`sql_qry`**: Component for executing SQL queries.
- **`obj_tbl`**: Object SQL results table or similar.
- **`qr_scanner`**: Component for scanning QR codes.
- **`websocket`**: Component for WebSocket communication.
### 1.3. Main / Module Components
These are components specific to main application sections or individual modules.
- **`menu`**:
- **`options`**: Various settings, show/hide content and options, limit, sorting options.
- **`actions`**: Various actions, sign in/out, email.
### 1.4. Object Menu
A standardized menu for interacting with objects.
- **Properties Displayed:** `id`, `name`, `group`, `priority`, `sort`, `alert`, `hide`, `enable`, `note`.
- **Future Properties:** `ext_id`, `ext_sys_id`, `code` (not yet ready).
- **Actions:** `create`, `view`, `edit`, `update`, `hide`, `disable`, `delete`, `alert` (message), `archive` (not yet ready).
- **Future Actions:** `copy`, `import`.
- **Sort Options:**
- `[default]`: `group > priority > sort (ASC/DESC) > alert > name`
- `[sort_updated]`: `group > priority > sort (ASC/DESC) > alert > updated_on > created_on`
- `[priority_updated]`: `group > priority > updated_on (ASC/DESC) > created_on`
- `[priority_name]`: `group > priority > name (ASC/DESC) > sort > alert > updated_on > created_on`
- `[name]`: `priority > name (ASC/DESC) > sort > alert > updated_on > created_on`
- `[created_on]`: `priority > created_on (ASC/DESC)`
- `[updated_on]`: `priority > updated_on (ASC/DESC) > created_on`
## 2. Pop-ups
Standardized structure for various types of pop-up elements.
- **`modal_header`**:
- `title`
- `close` button
- **`modal_main`**: Main content area of the modal.
- **`modal_meta`**: Meta-information section.
- **`modal_footer`**:
- `close` button
- **`Pop-up Modal (blocking)`**: A modal that blocks interaction with the rest of the page.
- `modal position`
- **`Pop-up Modal Inline`**: A modal that appears inline with content.
- `inline`, `inline-block`, `block` display options.
- **`Pop-up Dialog`**: A dialog box.
- `dialog position`
## 3. Containers
Generic container types used for layout and grouping.
### 3.1. Navigation
- `link`
- `download`
### 3.2. Forms
- `save` button/action
- `clear value` action
- `set null value` action
### 3.3. Other Containers
- `help`: Blue themed container.
- `info`: Blue themed container.
- `alert`: Yellow themed container.
- `warning`: Orange themed container.
- `error`: Red themed container.
- `message`: Green themed container.
## 4. CSS Styling for UI Elements
- **Warning/Hide Buttons:** `variant-soft-warning hover:variant-filled-warning`
- **Error/Delete/Disable Buttons:** `variant-soft-error hover:variant-filled-error`
- **Submenu:** `flex flex-row items-center justify-center gap-1`

90
documentation/DATA_STRUCTURES.md Normal file
View File

@@ -0,0 +1,90 @@
# Aether Project Data Structures
This document outlines the key data structures and their properties used within the Aether SvelteKit frontend project. It covers object properties, field definitions, and how data is managed.
## 1. Object Properties and Fields
### 1.1. Core Standard Fields
These fields are expected to be present in most Aether objects, providing a consistent base structure.
- `id`: Primary key for an object (internal use, often a UUID).
- `id_random`: Randomly generated ID for an object (often used for external exposure or URL parameters).
- `<object_type>_id_random`: Specific random ID for an object (e.g., `person_id_random`).
- `code`: Short, unique identifier.
- `name`: Display name.
- `enable`: Boolean for active/inactive status.
- `hide`: Boolean for visibility.
- `priority`: Numeric value for ordering.
- `sort`: Numeric value for ordering.
- `group`: Categorization string.
- `notes`: General notes/comments.
- `created_on`: Timestamp of creation.
- `updated_on`: Timestamp of last update.
### 1.2. Special Use Fields
Fields with specific purposes or conditional usage across different object types.
- `for_type`: Indicates the type of object this object is linked to (e.g., 'account', 'event').
- `for_id`: The ID of the object this object is linked to.
- `archive_on`: Timestamp indicating when an object was archived.
- `passcode`: A password or access code associated with an object.
- `external_id`: An identifier from an external system.
### 1.3. Configuration and JSON Fields
Fields designed to store structured data in JSON format.
- `cfg_json`: Configuration data for an object, stored as a JSON string.
- `data_json`: General purpose data for an object, stored as a JSON string.
- `linked_li_json`: A list of linked items, stored as a JSON string.
### 1.4. Special Generated Fields (Client-side)
These fields are generated on the client-side, primarily for facilitating UI logic, such as sorting. They are not typically stored in the backend database.
- `tmp_sort_1`: Temporary sort field 1.
- `tmp_sort_2`: Temporary sort field 2.
- `tmp_sort_3`: Temporary sort field 3.
### 1.5. Future Standard Fields
A list of potential future standard fields, often prefixed with `obj_`. These are conceptual and represent planned expansions to the data model.
- `obj_id`, `obj_ext_uid`, `obj_ext_id`, `obj_import_id`, `obj_code`, `obj_account_id`, `obj_passcode`, `obj_type`, `obj_type_ver_id`, `obj_name`, `obj_summary`, `obj_outline`, `obj_description`, `obj_enable`, `obj_enable_on`, `obj_archive_on`, `obj_hide`, `obj_priority`, `obj_sort`, `obj_group`, `obj_cfg_json`, `obj_notes`, `obj_created_on`, `obj_updated_on`.
## 2. Data Sorting
Standardized sorting orders are applied across various data lists to ensure consistent presentation.
- **Default/General Sorting:** `group > priority > sort > updated_on/created_on`
- **Specific Sorting (e.g., for time-based events):** `type > start_date/time > code or name`
## 3. Data Storage Mechanisms
### 3.1. Local Storage
Used for client-side persistence of various application states and configurations.
- `api`: Stores API-related settings and tokens.
- `app`: Stores global application settings and preferences.
- `core`: Stores settings and data specific to core modules.
- `<module>`: Stores settings and data specific to extended modules (e.g., `journals`, `events`).
- `<custom>`: Stores settings and data specific to custom modules (e.g., `idaa`).
### 3.2. IndexedDB (Dexie.js)
Used for more structured client-side data storage, often for caching, offline capabilities, and larger datasets.
- `ae_core_db`: The primary Dexie database instance for core application data.
- `<module>`: Module-specific database instances (e.g., `db_journals` for journal data).
- `<custom>`: Custom module-specific database instances (none currently defined, but reserved for future use).
### 3.3. IndexedDB LiveQuery Usage
Dexie's `liveQuery` is used to provide reactive data streams from IndexedDB.
- `lq__xyz_obj`: Represents a read-only liveQuery result for a single object.
- `lqw__xyz_obj`: Represents a writable liveQuery result, typically used for forms and data binding.
- **Note:** When using `lqw__xyz_obj`, developers must carefully manage updates to avoid conflicts with the underlying liveQuery and ensure data integrity.

93
documentation/NAMING_CONVENTIONS.md Normal file
View File

@@ -0,0 +1,93 @@
# Aether Project Naming Conventions
## 1. General Principles
- **Clarity:** Names should clearly convey their purpose and meaning.
- **Consistency:** Adhere strictly to these guidelines across the entire codebase.
- **Readability:** Prioritize names that are easy to read and understand.
- **Conciseness:** Avoid unnecessary verbosity, but not at the expense of clarity.
## 2. File Naming
- **Logic/Service Files:** `ae_<module>__<concept>.ts` (e.g., `ae_core__account.ts`, `ae_events__event.ts`)
- **Database Definition Files:** `db_<module>.ts` (e.g., `db_core.ts`, `db_journals.ts`)
- **Svelte Store Files:** `ae_<module>_stores.ts` (e.g., `ae_core_stores.ts`, `ae_journals_stores.ts`)
- **Svelte Components:**
- **Module-specific components:** `ae_comp__<module>__<component_name>.svelte` (e.g., `ae_comp__events__event_card.svelte`)
- **Generic/reusable components:** `element_<component_name>.svelte` (e.g., `element_input_file.svelte`, `element_qr_scanner_v2.svelte`)
- **SvelteKit Routes:** Follow SvelteKit's standard routing conventions (e.g., `+page.svelte`, `+layout.svelte`, `[id]/+page.svelte`).
- **CSS Files:** `ae-<module>-<purpose>.css` (e.g., `ae-c-idaa-light.css`, `ae-osit-default.css`)
## 3. Function and Variable Naming
- **Style:** Strictly `snake_case` for all function and variable names.
- **Deprecated:** `camelCase` should be refactored to `snake_case`.
- **Prefixes:**
- `load_ae_obj_id__<object_type>`: For loading a single Aether object by ID.
- `load_ae_obj_li__<object_type>`: For loading a list of Aether objects.
- `create_ae_obj__<object_type>`: For creating an Aether object.
- `update_ae_obj__<object_type>`: For updating an Aether object.
- `delete_ae_obj_id__<object_type>`: For deleting an Aether object by ID.
- `db_save_ae_obj_li__<object_type>`: For saving a list of Aether objects to IndexedDB.
- `db_update_ae_obj_id__<object_type>`: For updating an Aether object in IndexedDB.
- `process_ae_obj__<object_type>_props`: For module-specific data transformation functions.
- **Deprecated:** Ambiguous `handle_` prefixes should be replaced with more descriptive `snake_case` names (e.g., `handle_submit_form` -> `submit_form`).
## 4. Object and Property Naming
- **Singularity:** Use singular nouns for objects and properties (e.g., `example.id`, not `examples.id`).
- **IDs:**
- `id`: Primary key for an object (internal use, often a UUID).
- `<object_type>_id`: Specific ID for an object (e.g., `person_id`).
- `<object_type>_id_random`: Randomly generated ID for an object (often used for external exposure or URL parameters).
- `account_id`, `site_id`, `user_id`, etc.: Foreign keys.
- **Common Properties:**
- `code`: Short, unique identifier.
- `name`: Display name.
- `description`: Longer text description.
- `enable`: Boolean for active/inactive status.
- `hide`: Boolean for visibility.
- `priority`: Numeric value for ordering.
- `sort`: Numeric value for ordering.
- `group`: Categorization string.
- `notes`: General notes/comments.
- `created_on`: Timestamp of creation.
- `updated_on`: Timestamp of last update.
- **Special Use Properties:** `for_type`, `for_id`, `archive_on`, `passcode`, `external_id`.
- **Config/JSON Properties:** `cfg_json`, `data_json`, `linked_li_json`.
- **Special Generated Fields (Client-side):** `tmp_sort_1`, `tmp_sort_2`, `tmp_sort_3` (for client-side sorting).
## 5. List Suffixes
- **Simple Arrays:** Use `_li` suffix for simple, unordered arrays (e.g., `user_li`, `hosted_file_id_li`).
- **Key-Value Maps/Objects:** Use `_kv` suffix for key-value objects/maps (e.g., `user_kv`, `hosted_file_obj_kv`).
## 6. Interface and Type Naming
- **Style:** Use `PascalCase` for interface and type names (e.g., `Account`, `HostedFile`, `GenericCrudArgs`).
## 7. Constants
- **Style:** Use `SCREAMING_SNAKE_CASE` for constants (e.g., `MAX_RETRIES`, `DEFAULT_TIMEOUT`).
## 8. CSS Classes and IDs
- **Style:** Use `kebab-case` for CSS classes and IDs (e.g., `my-component-class`, `main-header-id`).
## 9. Data Sorting
- **Standard Order:** `group > priority > sort > updated_on/created_on`
- **Specific Order:** `type > start_date/time > code or name`
## 10. Local Storage and IndexedDB Keys
- **Local Storage:**
- `api`
- `app` (global)
- `core` (core modules)
- `<module>` (extended modules)
- `<custom>` (custom modules)
- **IndexedDB:**
- `ae_core_db`
- `<module>`
- `<custom>`

108
documentation/SVELTE_DEXIE_GUIDE.md Normal file
View File

@@ -0,0 +1,108 @@
# Svelte and Dexie.js Integration Guide
This document provides a guide to integrating Svelte (with a focus on Runes) and Dexie.js for building reactive web applications. It covers key concepts and best practices for managing reactivity between Svelte components and the Dexie.js database.
## Svelte 5 Migration Guide
Svelte 5 introduces "runes" as a new way to manage reactivity. This is a major change from previous versions of Svelte, and it's important to understand the breaking changes before migrating.
### Key Breaking Changes
- **`let` is no longer reactive:** In Svelte 4, any `let` variable declared in the top-level scope of a component was automatically reactive. In Svelte 5, you must explicitly declare reactive state using the `$state` rune.
- **`$:` is replaced by `$derived` and `$effect`:** The `$` label is no longer used for reactive statements. Instead, you should use the `$derived` rune for computed values and the `$effect` rune for side effects.
- **`export let` is replaced by `$props`:** Component props are now declared using the `$props` rune, which provides a more flexible and explicit way to define component APIs.
- **Event handling:** The `on:` directive is replaced by event attributes (e.g., `onclick`). Component events are now handled using callback props instead of `createEventDispatcher`.
- **Slots are replaced by snippets:** The `<slot>` element is replaced by the `{#snippet ...}` block, which provides a more powerful and flexible way to pass content to components.
For a complete list of breaking changes, refer to the [Svelte 5 migration guide](https://svelte.dev/docs/svelte/v5-migration-guide).
## Dexie.js Quick Reference
Dexie.js is a lightweight, minimalistic wrapper for IndexedDB that makes it easier to work with client-side databases.
### Key Classes and Methods
- **`Dexie`:** The main class for creating and managing IndexedDB databases.
- `new Dexie(databaseName)`: Creates a new database instance.
- `version(versionNumber).stores({ ... })`: Defines the database schema.
- **`Table`:** Represents an object store (table) in the database.
- `add(item)`: Adds a new item to the table.
- `put(item)`: Adds or updates an item in the table.
- `update(key, changes)`: Updates an existing item.
- `delete(key)`: Deletes an item by its primary key.
- `get(key)`: Retrieves an item by its primary key.
- `where(index)`: Starts a query using an index.
- `toArray()`: Retrieves all items from the table as an array.
- **`Collection`:** Represents a collection of items resulting from a query.
- `toArray()`: Retrieves all items in the collection as an array.
- `first()`: Retrieves the first item in the collection.
- `last()`: Retrieves the last item in the collection.
- `each(callback)`: Iterates over each item in the collection.
- `modify(changes)`: Updates all items in the collection.
- `delete()`: Deletes all items in the collection.
For a complete list of API methods, refer to the [Dexie.js API Reference](https://dexie.org/docs/API-Reference).
## Integrating Svelte Runes and Dexie.js
The combination of Svelte Runes and Dexie.js allows for the creation of highly reactive and efficient web applications.
### The `liveQuery` Function
Dexie.js provides a `liveQuery` function that returns an observable of the query result. This observable can be used to automatically update the UI whenever the data in the database changes.
### Using `liveQuery` with Svelte Runes
To use `liveQuery` with Svelte Runes, you can create a custom readable store that wraps the `liveQuery` observable. This store can then be used in your Svelte components to display and interact with the data.
**1. Create a `liveQuery` store:**
```typescript
import { liveQuery } from 'dexie';
import { readable } from 'svelte/store';
import { db } from './db'; // Your Dexie database instance
export function createLiveQueryStore<T>(query: () => T | Promise<T>) {
return readable<T | undefined>(undefined, (set) => {
const subscription = liveQuery(query).subscribe({
next: (result) => set(result),
error: (error) => console.error(error)
});
return () => subscription.unsubscribe();
});
}
```
**2. Use the `createLiveQueryStore` in your component:**
```html
<script>
import { createLiveQueryStore } from './stores';
import { db } from './db';
const friends = createLiveQueryStore(() => db.friends.toArray());
</script>
<ul>
{#if $friends} {#each $friends as friend}
<li>{friend.name}</li>
{/each} {/if}
</ul>
```
The `createLiveQueryStore` function creates a readable store that automatically updates whenever the data in the `friends` table changes. The `$friends` variable in the component will always contain the latest data from the database.
## Current Data Flow in `ae_journals` Module
The `ae_journals` module currently uses a manual, API-first caching strategy. It does not use Dexie.js's `liveQuery` function for reactivity.
### Data Flow
1. **Fetch from API:** The `load_ae_obj_id__journal` and `load_ae_obj_li__journal` functions are used to fetch data from the API.
2. **Process Data:** The `process_ae_obj__journal_props` and `process_ae_obj__journal_entry_props` functions are used to process the data before it's saved to the database. This includes parsing Markdown, creating temporary sorting fields, and combining passcodes.
3. **Save to IndexedDB:** The `db_save_ae_obj_li__ae_obj` function is used to save the processed data to the `journal` and `journal_entry` tables in the `ae_journals_db` IndexedDB database.
4. **Manual Store Updates:** The Svelte stores in `src/lib/ae_journals/ae_journals_stores.ts` are manually updated with the fetched data.
### Future Improvements
The current implementation could be improved by refactoring it to use Dexie.js's `liveQuery` function. This would simplify the code, reduce boilerplate, and improve the reactivity of the application. By using `liveQuery`, the UI would automatically update whenever the data in the IndexedDB database changes, without the need for manual store updates.