@indexeddb-orm/idb-orm 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,152 @@
+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/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/logger.d.ts

@@ -0,0 +1,12 @@
+export declare const createServiceLogger: (serviceName: string) => {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+};
+export declare const logger: {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,16 @@
+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) => {
+    return {
+        debug: (message, ...args) => log.debug(`[${serviceName}] ${message}`, ...args),
+        info: (message, ...args) => log.info(`[${serviceName}] ${message}`, ...args),
+        warn: (message, ...args) => log.warn(`[${serviceName}] ${message}`, ...args),
+        error: (message, ...args) => log.error(`[${serviceName}] ${message}`, ...args),
+    };
+};
+export const logger = createServiceLogger('indexeddb-orm');

package/eslint.config.js

@@ -0,0 +1,49 @@
+import js from '@eslint/js'
+import tseslint from 'typescript-eslint'
+import { globalIgnores } from 'eslint/config'
+import simpleImportSort from 'eslint-plugin-simple-import-sort'
+
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.ts'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+    ],
+    plugins: {
+      'simple-import-sort': simpleImportSort,
+    },
+    languageOptions: {
+      ecmaVersion: 2020,
+    },
+    rules: {
+      'semi': ['error', 'always'],
+      'quotes': ['error', 'single', { allowTemplateLiterals: true, avoidEscape: true }],
+      'comma-dangle': ['error', 'always-multiline'],
+      'object-curly-spacing': ['error', 'always'],
+      'array-bracket-spacing': ['error', 'never'],
+      'no-trailing-spaces': 'error',
+      'eol-last': ['error', 'always'],
+      'padding-line-between-statements': [
+        'error',
+        { blankLine: 'always', prev: '*', next: 'return' },
+      ],
+      'max-len': ['error', { code: 85, tabWidth: 2, ignoreUrls: true, ignoreStrings: true, ignoreTemplateLiterals: false, ignoreComments: false }],
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+      'object-curly-newline': [
+        'error',
+        {
+          ImportDeclaration: { multiline: true, minProperties: 2 },
+          ExportDeclaration: { multiline: true, minProperties: 2 },
+        }
+      ],
+      // Allow intentionally unused vars prefixed with _
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+    },
+  },
+])
+
+

package/homepage/favicon.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none">
+  <!-- Brand gradient background -->
+  <defs>
+    <linearGradient id="brand" x1="8" y1="8" x2="56" y2="56" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#667eea"/>
+      <stop offset="100%" stop-color="#764ba2"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="6" y="6" width="52" height="52" rx="14" fill="url(#brand)"/>
+
+  <!-- Globe icon (centered) -->
+  <g stroke="#ffffff" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round" fill="none">
+    <circle cx="32" cy="30" r="14"/>
+    <ellipse cx="32" cy="30" rx="9.2" ry="14"/>
+    <ellipse cx="32" cy="30" rx="14" ry="9.2"/>
+    <path d="M18 30h28"/>
+    <path d="M32 16v28"/>
+  </g>
+
+  <!-- Badge: circular, overlapping bottom-right for better composition -->
+  <!-- Soft shadow for separation on gradient -->
+  <circle cx="46" cy="46" r="10" fill="rgba(0,0,0,0.18)"/>
+  <circle cx="45.5" cy="45.5" r="10" fill="#ffffff"/>
+
+  <!-- Database cylinder inside badge -->
+  <g transform="translate(35.5,35.5)">
+    <!-- Use brand tint for cylinder to relate with background -->
+    <ellipse cx="10" cy="6.2" rx="6.6" ry="3" fill="#6e79ef"/>
+    <path d="M3.4 6.2v6.6c0 1.8 2.9 3.3 6.6 3.3s6.6-1.5 6.6-3.3V6.2" fill="#6e79ef"/>
+    <path d="M3.4 9.8c0 1.8 2.9 3.3 6.6 3.3s6.6-1.5 6.6-3.3" stroke="#cfd2ff" stroke-width="1.4" fill="none"/>
+  </g>
+
+  <!-- Subtle highlight on card -->
+  <circle cx="22" cy="20" r="6" fill="#ffffff" opacity="0.12"/>
+</svg>