@indexeddb-orm/idb-orm 0.0.1

package/src/services/SchemaBuilder.ts

@@ -0,0 +1,237 @@
+import {
+  getColumnMetadata, getCompoundIndexMetadata,
+} from '../metadata/Column';
+import { getEntityMetadata } from '../metadata/Entity';
+import type { EntityConstructor } from '../types';
+import { logger } from '../utils/logger';
+import { getDefinedCompoundIndexes } from './EntityRegistry';
+
+export interface TableSchema {
+  tableName: string;
+  schema: string;
+}
+
+export interface SchemaChange {
+  tableName: string;
+  changeType: 'added' | 'removed' | 'modified';
+  oldSchema?: string;
+  newSchema?: string;
+}
+
+export class SchemaBuilder {
+  /**
+   * Build indexeddb schema from entities
+   * @param entities - Array of entity constructors
+   * @returns IndexedDB schema object with table definitions
+   *
+   * @example
+   * const schema = SchemaBuilder.buildSchema([User, Post]);
+   */
+  static buildSchema(entities: EntityConstructor[]): Record<string, string> {
+    const schema: Record<string, string> = {};
+
+    schema.migrationMetadata = 'key, value, updatedAt';
+
+    entities.forEach(entity => {
+      const metadata = getEntityMetadata(entity);
+      const tableName = metadata?.tableName || entity.name.toLowerCase() + 's';
+
+      const columns = getColumnMetadata(entity);
+      const compoundIndexes = getDefinedCompoundIndexes(entity)
+        || getCompoundIndexMetadata(entity);
+
+      let primaryKeySpec = '';
+      const indexSpecs: string[] = [];
+
+      Object.entries(columns).forEach(([propertyKey, columnMeta]) => {
+        if (columnMeta.primaryKey) {
+          primaryKeySpec = columnMeta.autoIncrement
+          ? `++${propertyKey}`
+          : propertyKey;
+        } else if (columnMeta.unique) {
+          indexSpecs.push(`&${propertyKey}`);
+        } else if (columnMeta.indexed) {
+          indexSpecs.push(`${propertyKey}`);
+        }
+      });
+
+      const compoundIndexStrings: string[] = [];
+
+      compoundIndexes.forEach(compoundIndex => {
+        const indexColumns = compoundIndex.columns.join('+');
+        const bracketed = `[${indexColumns}]`;
+        const spec = compoundIndex.unique ? `&${bracketed}` : `${bracketed}`;
+
+        compoundIndexStrings.push(spec);
+      });
+
+      const parts = [
+        primaryKeySpec, ...indexSpecs, ...compoundIndexStrings,
+      ].filter(Boolean);
+
+      schema[tableName] = parts.join(',');
+
+      if (!schema[tableName]) {
+        schema[tableName] = '++id';
+      }
+    });
+
+    return schema;
+  }
+
+  /**
+   * Build detailed table schemas for comparison
+   * @param entities - Array of entity constructors
+   * @returns Array of detailed table schema objects
+   *
+   * @example
+   * const tables = SchemaBuilder.buildTableSchemas([User, Post]);
+   */
+  static buildTableSchemas(entities: EntityConstructor[]): TableSchema[] {
+    return entities.map(entity => {
+      const metadata = getEntityMetadata(entity);
+      const tableName = metadata?.tableName || entity.name.toLowerCase() + 's';
+      const columns = getColumnMetadata(entity);
+      const compoundIndexes = getCompoundIndexMetadata(entity);
+
+      let primaryKeySpec = '';
+      const indexSpecs: string[] = [];
+
+      Object.entries(columns).forEach(([propertyKey, columnMeta]) => {
+        if (columnMeta.primaryKey) {
+          primaryKeySpec = columnMeta.autoIncrement
+          ? `++${propertyKey}`
+          : propertyKey;
+        } else if (columnMeta.unique) {
+          indexSpecs.push(`&${propertyKey}`);
+        } else if (columnMeta.indexed) {
+          indexSpecs.push(`${propertyKey}`);
+        }
+      });
+
+      const compoundIndexStrings: string[] = [];
+
+      compoundIndexes.forEach(compoundIndex => {
+        const indexColumns = compoundIndex.columns.join('+');
+        const bracketed = `[${indexColumns}]`;
+        const spec = compoundIndex.unique ? `&${bracketed}` : `${bracketed}`;
+        compoundIndexStrings.push(spec);
+      });
+
+      const parts = [
+        primaryKeySpec, ...indexSpecs, ...compoundIndexStrings,
+      ].filter(Boolean);
+
+      return {
+        tableName,
+        schema: parts.join(','),
+      };
+    });
+  }
+
+  /**
+   * Generate hash for schema to detect changes
+   * @param schema - Schema object to hash
+   * @returns Hash string for schema comparison
+   *
+   * @example
+   * const hash = SchemaBuilder.generateSchemaHash(schema);
+   */
+  static generateSchemaHash(schema: Record<string, string>): string {
+    const schemaString = JSON.stringify(schema, Object.keys(schema).sort());
+
+    return btoa(schemaString).slice(0, 16);
+  }
+
+  /**
+   * Compare two schema arrays and return changes
+   * @param oldSchemas - Previous schema array
+   * @param newSchemas - Current schema array
+   * @returns Array of schema changes detected
+   *
+   * @example
+   * const changes = SchemaBuilder.compareSchemas(oldSchemas, newSchemas);
+   */
+  static compareSchemas(
+    oldSchemas: TableSchema[],
+    newSchemas: TableSchema[],
+  ): SchemaChange[] {
+    const changes: SchemaChange[] = [];
+    const oldSchemaMap = new Map(oldSchemas.map(s => [s.tableName, s]));
+    const newSchemaMap = new Map(newSchemas.map(s => [s.tableName, s]));
+
+    newSchemas.forEach(newSchema => {
+      if (!oldSchemaMap.has(newSchema.tableName)) {
+        changes.push({
+          tableName: newSchema.tableName,
+          changeType: 'added',
+          newSchema: newSchema.schema,
+        });
+      }
+    });
+
+    oldSchemas.forEach(oldSchema => {
+      if (!newSchemaMap.has(oldSchema.tableName)) {
+        changes.push({
+          tableName: oldSchema.tableName,
+          changeType: 'removed',
+          oldSchema: oldSchema.schema,
+        });
+      }
+    });
+
+    newSchemas.forEach(newSchema => {
+      const oldSchema = oldSchemaMap.get(newSchema.tableName);
+
+      if (oldSchema && oldSchema.schema !== newSchema.schema) {
+        changes.push({
+          tableName: newSchema.tableName,
+          changeType: 'modified',
+          oldSchema: oldSchema.schema,
+          newSchema: newSchema.schema,
+        });
+      }
+    });
+
+    return changes;
+  }
+
+  /**
+   * Store table schemas in localStorage
+   * @param dbName - Database name for key generation
+   * @param tableSchemas - Array of table schemas to store
+   *
+   * @example
+   * SchemaBuilder.storeTableSchemas('app-db', tables);
+   */
+  static storeTableSchemas(dbName: string, tableSchemas: TableSchema[]): void {
+    const key = `${dbName}_table_schemas`;
+    const serialized = JSON.stringify(tableSchemas);
+
+    localStorage.setItem(key, serialized);
+  }
+
+  /**
+   * Get stored table schemas from localStorage
+   * @param dbName - Database name for key lookup
+   * @returns Array of stored table schemas or empty array if none found
+   *
+   * @example
+   * const tables = SchemaBuilder.getStoredTableSchemas('app-db');
+   */
+  static getStoredTableSchemas(dbName: string): TableSchema[] {
+    const key = `${dbName}_table_schemas`;
+    const stored = localStorage.getItem(key);
+    if (!stored) {
+      return [];
+    }
+
+    try {
+      return JSON.parse(stored);
+    } catch (error) {
+      logger.error('Failed to parse stored table schemas:', error);
+
+      return [];
+    }
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,7 @@
+export { AggregationService } from './AggregationService';
+export { BaseEntity } from './BaseEntity';
+export { CloudSyncService } from './CloudSyncService';
+export { EntitySchema } from './EntitySchema';
+export { MigrationManager } from './MigrationManager';
+export { RelationLoader } from './RelationLoader';
+export { SchemaBuilder } from './SchemaBuilder';

package/src/types.d.ts

@@ -0,0 +1 @@
+declare module 'dexie-cloud-addon';

package/src/types.ts

@@ -0,0 +1,169 @@
+import type Dexie from 'dexie';
+import type { Table } from 'dexie';
+import { z } from 'zod';
+
+import { BaseEntity } from './services/BaseEntity';
+
+/**
+ * Constructor type for ORM entities.
+ */
+export interface EntityConstructor<T extends BaseEntity = BaseEntity> {
+  new (): T;
+  schema?: z.ZodSchema;
+  tableName?: string;
+}
+
+/**
+ * Generic plain object shape for entity instances used in serialization.
+ */
+export interface EntityInstance {
+  id?: number | string;
+  [key: string]: unknown;
+}
+
+/**
+ * Options for an entity column.
+ */
+export interface ColumnOptions {
+  kind?: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  unique?: boolean;
+  indexed?: boolean;
+  required?: boolean;
+  default?: unknown;
+  primaryKey?: boolean;
+  autoIncrement?: boolean;
+}
+
+/**
+ * Definition of a compound index across multiple columns.
+ */
+export interface CompoundIndexOptions {
+  name?: string;
+  unique?: boolean;
+  columns: string[];
+}
+
+export type RelationType = 'one-to-one' | 'one-to-many' | 'many-to-many';
+
+/**
+ * Configuration for a relation between two entities.
+ */
+export interface RelationOptions {
+  type: RelationType;
+  target: EntityConstructor | string;
+  /** Foreign key for one-to-many and many-to-many relations. */
+  foreignKey?: string;
+  /** Name of the join table for many-to-many relations. */
+  joinTable?: string;
+  /** If true, related records are deleted automatically. */
+  cascade?: boolean;
+  /** If true, the relation is auto-loaded with the entity. */
+  eager?: boolean;
+}
+
+/**
+ * Internal metadata stored for a relation decorator.
+ */
+export interface RelationMetadata extends RelationOptions {
+  propertyKey: string;
+}
+
+/**
+ * Options for configuring an entity class.
+ */
+export interface EntityOptions {
+  tableName?: string;
+  schema?: z.ZodSchema;
+  timestamps?: boolean;
+}
+
+/**
+ * Result of entity validation.
+ */
+export interface ValidationResult {
+  isValid: boolean;
+  errors: string[];
+}
+
+/**
+ * A single database migration step.
+ */
+export interface Migration {
+  version: number;
+  name: string;
+  up: (_db: Dexie) => Promise<void>;
+  down?: (_db: Dexie) => Promise<void>;
+}
+
+/**
+ * Configuration for optional cloud synchronization.
+ */
+export interface CloudSyncConfig {
+  /** Base URL of the synchronization server. */
+  databaseUrl: string;
+  /** If enabled, queue changes and retry when offline. */
+  enableOfflineSupport?: boolean;
+  /** Periodic sync interval in milliseconds. */
+  syncInterval?: number;
+}
+
+/**
+ * Configuration for creating a Database instance.
+ */
+export interface DatabaseConfig {
+  /** Name of the IndexedDB database. */
+  name: string;
+  /** Schema version number. */
+  version: number;
+  /** List of registered entity classes to include in the schema. */
+  entities: EntityConstructor[];
+  /** Strategy for handling schema changes. */
+  onSchemaChangeStrategy?: 'selective' | 'all';
+  /** Optional list of migrations to execute. */
+  migrations?: Migration[];
+  /** Optional cloud synchronization configuration. */
+  cloudSync?: CloudSyncConfig;
+}
+
+export type TableGetter<T extends BaseEntity> = () => Table<T>;
+/**
+ * Options for the aggregation query on a specific entity.
+ */
+export interface AggregationOptions<T extends BaseEntity> {
+  /** Partial where filter applied to records before aggregation. */
+  where?: Partial<T>;
+  count?: boolean;
+  sum?: (keyof T)[];
+  avg?: (keyof T)[];
+  min?: (keyof T)[];
+  max?: (keyof T)[];
+  groupBy?: keyof T;
+  include?: string[];
+  limit?: number;
+  sort?: {
+    field: keyof T;
+    direction: 'asc' | 'desc';
+  };
+}
+
+/**
+ * Result returned by the aggregation service.
+ */
+export interface AggregationResult {
+  count?: number;
+  sum?: Record<string, number>;
+  avg?: Record<string, number>;
+  min?: Record<string, number>;
+  max?: Record<string, number>;
+  groups?: Array<{
+    key: unknown;
+    count: number;
+    sum?: Record<string, number>;
+    avg?: Record<string, number>;
+    min?: Record<string, number>;
+    max?: Record<string, number>;
+  }>;
+  data?: unknown[];
+}
+
+

package/src/utils/logger.ts

@@ -0,0 +1,40 @@
+import log from 'loglevel';
+
+const isDevHost = (
+  typeof window !== 'undefined' &&
+  typeof window.location !== 'undefined' &&
+  (
+    window.location.hostname === 'localhost' ||
+    window.location.hostname === '127.0.0.1' ||
+    window.location.hostname === '0.0.0.0'
+  )
+);
+
+log.setLevel(isDevHost ? 'debug' : 'error');
+
+export const createServiceLogger = (serviceName: string) => {
+  return {
+    debug: (message: string, ...args: unknown[]) =>
+      log.debug(
+        `[${serviceName}] ${message}`,
+        ...args,
+      ),
+    info: (message: string, ...args: unknown[]) =>
+      log.info(
+        `[${serviceName}] ${message}`,
+        ...args,
+      ),
+    warn: (message: string, ...args: unknown[]) =>
+      log.warn(
+        `[${serviceName}] ${message}`,
+        ...args,
+      ),
+    error: (message: string, ...args: unknown[]) =>
+      log.error(
+        `[${serviceName}] ${message}`,
+        ...args,
+      ),
+  };
+};
+
+export const logger = createServiceLogger('indexeddb-orm');

package/svelte-demo-app/README.md

@@ -0,0 +1,61 @@
+# Dexie ORM Demo App
+
+A demonstration app showcasing the capabilities of the **Dexie ORM for IndexedDB** library.
+
+## Library Features
+
+- **Entity Configuration** - define entities using `defineEntity()`
+- **Automatic Schema** - automatic schema generation with primary keys and indexes
+- **Relations** - entity relationships with helpers
+- **Zod Validation** - runtime validation
+- **Aggregations** - aggregate functions (count, avg, sum)
+- **Live Queries** - reactive queries with `useLiveQuery()`
+- **TypeScript** - full type safety
+- **Cloud Sync** - synchronization with Dexie Cloud
+
+## Quick Start
+
+### Requirements
+- Node.js 18+
+- npm or yarn
+
+### Installation and Running
+
+1. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+2. **Run in development mode:**
+   ```bash
+   npm run dev
+   ```
+
+3. **Open in browser:**
+   ```
+   http://localhost:5173
+   ```
+
+### Production Build
+
+```bash
+npm run build
+```
+
+## 📱 App Features
+
+### Admin Tab
+- **Overview** - library capabilities overview
+- **Admin Actions** - function testing buttons
+- **Live Query Demo** - reactive queries demonstration
+- **TypeScript Demo** - type safety testing
+- **Posts Demo** - advanced queries and aggregations
+
+### Cloud Sync Tab
+- **Sync Status** - synchronization status
+- **Sync Controls** - synchronization management buttons
+- **Instructions** - configuration instructions
+
+## More Information
+
+For more information visit our official [page](https://idb-orm.com).