@stonyx/orm 0.2.1-beta.90 → 0.2.1-beta.92

package/dist/hooks.d.ts

@@ -2,18 +2,31 @@
  * Middleware-based hooks registry for ORM operations.
  * Unlike event-based hooks, middleware hooks run sequentially and can halt operations.
  */
+/** Context object passed to before/after hook handlers. */
 export interface HookContext {
+    /** Model name (e.g. 'user', 'animal'). */
     model: string;
+    /** Operation name: 'create', 'update', 'delete', 'get', or 'list'. */
     operation: string;
+    /** The incoming HTTP request object. */
     request?: unknown;
+    /** URL route parameters (e.g. { id: '42' }). */
     params?: Record<string, string>;
+    /** Parsed request body for create/update operations. */
     body?: Record<string, unknown>;
+    /** URL query string parameters. */
     query?: Record<string, string>;
+    /** Mutable state bag shared across hooks within a single request. */
     state?: Record<string, unknown>;
+    /** Previous record state (available in update hooks). */
     oldState?: unknown;
+    /** Target record ID for single-record operations. */
     recordId?: string | number;
+    /** Response data (available in after hooks). */
     response?: unknown;
+    /** The affected record (available in after hooks for create/update/delete). */
     record?: unknown;
+    /** The affected records (available in after hooks for list operations). */
     records?: unknown[];
     [key: string]: unknown;
 }

package/dist/mysql/schema-introspector.d.ts

@@ -1,7 +1,7 @@
 import type { ForeignKeyDef, ModelSchema, ViewSchema, SnapshotEntry } from '../types/orm-types.js';
 export declare function introspectModels(): Record<string, ModelSchema>;
 export declare function buildTableDDL(name: string, schema: ModelSchema, allSchemas?: Record<string, ModelSchema>): string;
-export declare function getTopologicalOrder(schemas: Record<string, ModelSchema>): string[];
+export { getTopologicalOrder } from '../schema-helpers.js';
 export declare function introspectViews(): Record<string, ViewSchema>;
 export declare function buildViewDDL(name: string, viewSchema: ViewSchema, modelSchemas?: Record<string, ModelSchema>): string;
 export declare function viewSchemasToSnapshot(viewSchemas: Record<string, ViewSchema>): Record<string, ViewSnapshotEntry>;

package/dist/mysql/schema-introspector.js

@@ -4,21 +4,8 @@ import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from '../plural-registry.js';
 import { dbKey } from '../db.js';
 import { AggregateProperty } from '../aggregates.js';
+import { getRelationshipInfo, sanitizeTableName } from '../schema-helpers.js';
 import ModelProperty from '../model-property.js';
-function getRelationshipInfo(property) {
-    if (typeof property !== 'function')
-        return null;
-    const relType = property.__relationshipType;
-    const modelName = property.__relatedModelName || null;
-    if (relType === 'belongsTo')
-        return { type: 'belongsTo', modelName };
-    if (relType === 'hasMany')
-        return { type: 'hasMany', modelName };
-    return null;
-}
-function sanitizeTableName(name) {
-    return name.replace(/[-/]/g, '_');
-}
 export function introspectModels() {
     const { models } = Orm.instance;
     const schemas = {};
@@ -112,28 +99,7 @@ function getReferencedIdType(tableName, allSchemas) {
     // Default to INT if referenced table not found in schemas
     return 'INT';
 }
-export function getTopologicalOrder(schemas) {
-    const visited = new Set();
-    const order = [];
-    function visit(name) {
-        if (visited.has(name))
-            return;
-        visited.add(name);
-        const schema = schemas[name];
-        if (!schema)
-            return;
-        // Visit dependencies (belongsTo targets) first
-        for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
-            if (targetModelName)
-                visit(targetModelName);
-        }
-        order.push(name);
-    }
-    for (const name of Object.keys(schemas)) {
-        visit(name);
-    }
-    return order;
-}
+export { getTopologicalOrder } from '../schema-helpers.js';
 export function introspectViews() {
     const orm = Orm.instance;
     if (!orm.views)

package/dist/orm-request.js

@@ -470,5 +470,6 @@ export default class OrmRequest extends Request {
             return 403;
         if (typeof access === 'function')
             state.filter = access;
+        return undefined;
     }
 }

package/dist/postgres/migration-generator.js

@@ -1,4 +1,5 @@
 import { introspectModels, introspectViews, buildTableDDL, buildViewDDL, buildVectorIndexDDL, schemasToSnapshot, viewSchemasToSnapshot, getTopologicalOrder } from './schema-introspector.js';
+import { buildCreateHypertable, buildEnableCompression, buildCompressionPolicy } from '../timescale/query-builder.js';
 import { readFile, createFile, createDirectory, fileExists } from '@stonyx/utils/file';
 import path from 'path';
 import config from 'stonyx/config';
@@ -41,6 +42,24 @@ export async function generateMigration(description = 'migration', configKey = '
         }
         downStatements.unshift(`DROP TABLE IF EXISTS "${schemas[name].table}" CASCADE;`);
     }
+    // Hypertable conversion + compression (TimescaleDB only)
+    if (configKey === 'timescale') {
+        for (const name of addedOrdered) {
+            const schema = schemas[name];
+            if (!schema.hypertable)
+                continue;
+            const { timeColumn, chunkInterval } = schema.hypertable;
+            upStatements.push(buildCreateHypertable(schema.table, timeColumn, { chunkInterval }).sql + ';');
+            if (schema.hypertable.compress) {
+                const { segmentBy, orderBy, after } = schema.hypertable.compress;
+                upStatements.push(buildEnableCompression(schema.table, segmentBy, orderBy).sql + ';');
+                if (after) {
+                    upStatements.push(buildCompressionPolicy(schema.table, after).sql + ';');
+                }
+            }
+            downStatements.unshift('-- Hypertable conversion is not reversible; table drop handles cleanup');
+        }
+    }
     // Removed tables (warn only, commented out)
     for (const name of diff.removedModels) {
         upStatements.push(`-- WARNING: Model '${name}' was removed. Uncomment to drop table:`);

package/dist/postgres/schema-introspector.d.ts

@@ -1,4 +1,4 @@
-import type { ForeignKeyDef, ModelSchema, ViewSchema } from '../types/orm-types.js';
+import type { ForeignKeyDef, HypertableConfig, ModelSchema, ViewSchema } from '../types/orm-types.js';
 interface ViewSnapshotEntry {
     viewName: string;
     source: string;
@@ -14,6 +14,7 @@ interface ModelSnapshotEntry {
     columns: Record<string, string>;
     foreignKeys: Record<string, ForeignKeyDef>;
     vectorColumns?: Record<string, number>;
+    hypertable?: HypertableConfig;
 }
 export declare function introspectModels(): Record<string, ModelSchema>;
 export declare function buildTableDDL(name: string, schema: ModelSchema, allSchemas?: Record<string, ModelSchema>): string;
@@ -21,9 +22,8 @@ export declare function buildTableDDL(name: string, schema: ModelSchema, allSche
  * Build HNSW index DDL for vector columns on a model.
  */
 export declare function buildVectorIndexDDL(name: string, schema: ModelSchema): string[];
-export declare function getTopologicalOrder(schemas: Record<string, ModelSchema>): string[];
+export { getTopologicalOrder } from '../schema-helpers.js';
 export declare function introspectViews(): Record<string, ViewSchema>;
 export declare function buildViewDDL(name: string, viewSchema: ViewSchema, modelSchemas?: Record<string, ModelSchema>): string;
 export declare function viewSchemasToSnapshot(viewSchemas: Record<string, ViewSchema>): Record<string, ViewSnapshotEntry>;
 export declare function schemasToSnapshot(schemas: Record<string, ModelSchema>): Record<string, ModelSnapshotEntry>;
-export {};

package/dist/postgres/schema-introspector.js

@@ -4,21 +4,8 @@ import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from '../plural-registry.js';
 import { dbKey } from '../db.js';
 import { AggregateProperty } from '../aggregates.js';
+import { getRelationshipInfo, sanitizeTableName } from '../schema-helpers.js';
 import ModelProperty from '../model-property.js';
-function getRelationshipInfo(property) {
-    if (typeof property !== 'function')
-        return null;
-    const relType = property.__relationshipType;
-    const modelName = property.__relatedModelName || null;
-    if (relType === 'belongsTo')
-        return { type: 'belongsTo', modelName };
-    if (relType === 'hasMany')
-        return { type: 'hasMany', modelName };
-    return null;
-}
-function sanitizeTableName(name) {
-    return name.replace(/[-/]/g, '_');
-}
 export function introspectModels() {
     const { models } = Orm.instance;
     const schemas = {};
@@ -68,6 +55,7 @@ export function introspectModels() {
                 column: 'id',
             };
         }
+        const hypertable = modelClass.hypertable;
         schemas[name] = {
             table: sanitizeTableName(getPluralName(name)),
             idType,
@@ -75,19 +63,24 @@ export function introspectModels() {
             foreignKeys,
             relationships,
             vectorColumns,
+            hypertable: hypertable || undefined,
             memory: modelClass.memory === true,
         };
     }
     return schemas;
 }
 export function buildTableDDL(name, schema, allSchemas = {}) {
-    const { idType, columns, foreignKeys } = schema;
+    const { idType, columns, foreignKeys, hypertable } = schema;
     const table = sanitizeTableName(schema.table);
     const lines = [];
+    const useCompositePK = hypertable && idType !== 'string';
     // Primary key
     if (idType === 'string') {
         lines.push('  "id" VARCHAR(255) PRIMARY KEY');
     }
+    else if (useCompositePK) {
+        lines.push('  "id" INTEGER GENERATED ALWAYS AS IDENTITY');
+    }
     else {
         lines.push('  "id" INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY');
     }
@@ -101,13 +94,22 @@ export function buildTableDDL(name, schema, allSchemas = {}) {
         lines.push(`  "${fkCol}" ${refIdType}`);
     }
     // Timestamps
-    lines.push('  "created_at" TIMESTAMPTZ DEFAULT NOW()');
+    if (useCompositePK) {
+        lines.push('  "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()');
+    }
+    else {
+        lines.push('  "created_at" TIMESTAMPTZ DEFAULT NOW()');
+    }
     lines.push('  "updated_at" TIMESTAMPTZ DEFAULT NOW()');
     // Foreign key constraints
     for (const [fkCol, fkDef] of Object.entries(foreignKeys)) {
         const refTable = sanitizeTableName(fkDef.references);
         lines.push(`  FOREIGN KEY ("${fkCol}") REFERENCES "${refTable}"("${fkDef.column}") ON DELETE SET NULL`);
     }
+    // Composite primary key for hypertable models
+    if (useCompositePK) {
+        lines.push(`  PRIMARY KEY ("id", "${hypertable.timeColumn}")`);
+    }
     return `CREATE TABLE IF NOT EXISTS "${table}" (\n${lines.join(',\n')}\n)`;
 }
 /**
@@ -129,28 +131,7 @@ function getReferencedIdType(tableName, allSchemas) {
     }
     return 'INTEGER';
 }
-export function getTopologicalOrder(schemas) {
-    const visited = new Set();
-    const order = [];
-    function visit(name) {
-        if (visited.has(name))
-            return;
-        visited.add(name);
-        const schema = schemas[name];
-        if (!schema)
-            return;
-        // Visit dependencies (belongsTo targets) first
-        for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
-            if (targetModelName)
-                visit(targetModelName);
-        }
-        order.push(name);
-    }
-    for (const name of Object.keys(schemas)) {
-        visit(name);
-    }
-    return order;
-}
+export { getTopologicalOrder } from '../schema-helpers.js';
 export function introspectViews() {
     const orm = Orm.instance;
     if (!orm.views)
@@ -308,6 +289,7 @@ export function schemasToSnapshot(schemas) {
             ...(schema.vectorColumns && Object.keys(schema.vectorColumns).length > 0
                 ? { vectorColumns: { ...schema.vectorColumns } }
                 : {}),
+            ...(schema.hypertable ? { hypertable: schema.hypertable } : {}),
         };
     }
     return snapshot;

package/dist/schema-helpers.d.ts

@@ -0,0 +1,20 @@
+import type { ModelSchema } from './types/orm-types.js';
+export interface SchemaRelationshipInfo {
+    type: 'belongsTo' | 'hasMany';
+    modelName: string | null;
+}
+/**
+ * Detect relationship type and target model from a model property function.
+ * Returns null if the property is not a relationship.
+ */
+export declare function getRelationshipInfo(property: unknown): SchemaRelationshipInfo | null;
+/**
+ * Sanitize a model/table name for use in SQL identifiers.
+ * Replaces hyphens and slashes with underscores.
+ */
+export declare function sanitizeTableName(name: string): string;
+/**
+ * Sort model schemas in dependency order (belongsTo targets before dependents).
+ * Uses depth-first traversal to ensure referenced tables are created first.
+ */
+export declare function getTopologicalOrder(schemas: Record<string, ModelSchema>): string[];

package/dist/schema-helpers.js

@@ -0,0 +1,48 @@
+/**
+ * Detect relationship type and target model from a model property function.
+ * Returns null if the property is not a relationship.
+ */
+export function getRelationshipInfo(property) {
+    if (typeof property !== 'function')
+        return null;
+    const relType = property.__relationshipType;
+    const modelName = property.__relatedModelName || null;
+    if (relType === 'belongsTo')
+        return { type: 'belongsTo', modelName };
+    if (relType === 'hasMany')
+        return { type: 'hasMany', modelName };
+    return null;
+}
+/**
+ * Sanitize a model/table name for use in SQL identifiers.
+ * Replaces hyphens and slashes with underscores.
+ */
+export function sanitizeTableName(name) {
+    return name.replace(/[-/]/g, '_');
+}
+/**
+ * Sort model schemas in dependency order (belongsTo targets before dependents).
+ * Uses depth-first traversal to ensure referenced tables are created first.
+ */
+export function getTopologicalOrder(schemas) {
+    const visited = new Set();
+    const order = [];
+    function visit(name) {
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        const schema = schemas[name];
+        if (!schema)
+            return;
+        // Visit dependencies (belongsTo targets) first
+        for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
+            if (targetModelName)
+                visit(targetModelName);
+        }
+        order.push(name);
+    }
+    for (const name of Object.keys(schemas)) {
+        visit(name);
+    }
+    return order;
+}

package/dist/store.js

@@ -119,14 +119,14 @@ export default class Store {
     unloadRecord(model, id, options = {}) {
         const modelStore = this.data.get(model);
         if (!modelStore) {
-            console.warn(`[Store] Cannot unload record: model "${model}" not found in store`);
+            console.warn(`[Store] Cannot unload record: model "${model}" not found in store — ensure the model is registered before unloading`);
             return;
         }
         if (typeof id !== 'string' && typeof id !== 'number')
             return;
         const raw = modelStore.get(id);
         if (!raw || !isStoreRecord(raw)) {
-            console.warn(`[Store] Cannot unload record: ${model}:${id} not found in store`);
+            console.warn(`[Store] Cannot unload record: ${model}:${id} not found in store — it may have already been unloaded`);
             return;
         }
         const record = raw;
@@ -145,7 +145,7 @@ export default class Store {
     unloadAllRecords(model, options = {}) {
         const modelStore = this.data.get(model);
         if (!modelStore) {
-            console.warn(`[Store] Cannot unload all records: model "${model}" not found in store`);
+            console.warn(`[Store] Cannot unload all records: model "${model}" not found in store — ensure the model is registered before unloading`);
             return;
         }
         const recordIds = Array.from(modelStore.keys());

package/dist/types/orm-types.d.ts

@@ -86,6 +86,15 @@ export interface ForeignKeyDef {
     references: string;
     column: string;
 }
+export interface HypertableConfig {
+    timeColumn: string;
+    chunkInterval?: string;
+    compress?: {
+        segmentBy?: string;
+        orderBy?: string;
+        after?: string;
+    };
+}
 export interface ModelSchema {
     table: string;
     idType: string;
@@ -96,6 +105,7 @@ export interface ModelSchema {
         hasMany: Record<string, string | null>;
     };
     vectorColumns?: Record<string, number>;
+    hypertable?: HypertableConfig;
     memory: boolean;
 }
 export interface ViewSchema {
@@ -135,6 +145,7 @@ export interface SnapshotEntry {
     columns?: Record<string, string>;
     foreignKeys?: Record<string, ForeignKeyDef>;
     vectorColumns?: Record<string, number>;
+    hypertable?: HypertableConfig;
     isView?: boolean;
     viewName?: string;
     source?: string;

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.90",
+  "version": "0.2.1-beta.92",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/hooks.ts

@@ -19,18 +19,31 @@
  * Unlike event-based hooks, middleware hooks run sequentially and can halt operations.
  */
 
+/** Context object passed to before/after hook handlers. */
 export interface HookContext {
+  /** Model name (e.g. 'user', 'animal'). */
   model: string;
+  /** Operation name: 'create', 'update', 'delete', 'get', or 'list'. */
   operation: string;
+  /** The incoming HTTP request object. */
   request?: unknown;
+  /** URL route parameters (e.g. { id: '42' }). */
   params?: Record<string, string>;
+  /** Parsed request body for create/update operations. */
   body?: Record<string, unknown>;
+  /** URL query string parameters. */
   query?: Record<string, string>;
+  /** Mutable state bag shared across hooks within a single request. */
   state?: Record<string, unknown>;
+  /** Previous record state (available in update hooks). */
   oldState?: unknown;
+  /** Target record ID for single-record operations. */
   recordId?: string | number;
+  /** Response data (available in after hooks). */
   response?: unknown;
+  /** The affected record (available in after hooks for create/update/delete). */
   record?: unknown;
+  /** The affected records (available in after hooks for list operations). */
   records?: unknown[];
   [key: string]: unknown;
 }

package/src/mysql/schema-introspector.ts

@@ -4,39 +4,15 @@ import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from '../plural-registry.js';
 import { dbKey } from '../db.js';
 import { AggregateProperty } from '../aggregates.js';
+import { getRelationshipInfo, sanitizeTableName } from '../schema-helpers.js';
 import type { ForeignKeyDef, ModelSchema, ViewSchema, SnapshotEntry } from '../types/orm-types.js';
 import ModelProperty from '../model-property.js';
 
-interface RelationshipInfo {
-  type: 'belongsTo' | 'hasMany';
-  modelName: string | null;
-}
-
 interface JoinClause {
   table: string;
   condition: string;
 }
 
-interface RelationshipProperty {
-  __relatedModelName?: string | null;
-  __relationshipType?: string;
-}
-
-function getRelationshipInfo(property: unknown): RelationshipInfo | null {
-  if (typeof property !== 'function') return null;
-  const relType = (property as RelationshipProperty).__relationshipType;
-  const modelName = (property as RelationshipProperty).__relatedModelName || null;
-
-  if (relType === 'belongsTo') return { type: 'belongsTo', modelName };
-  if (relType === 'hasMany') return { type: 'hasMany', modelName };
-
-  return null;
-}
-
-function sanitizeTableName(name: string): string {
-  return name.replace(/[-/]/g, '_');
-}
-
 export function introspectModels(): Record<string, ModelSchema> {
   const { models } = (Orm as unknown as { instance: { models: Record<string, unknown>; transforms: Record<string, unknown> } }).instance;
   const schemas: Record<string, ModelSchema> = {};
@@ -143,31 +119,7 @@ function getReferencedIdType(tableName: string, allSchemas: Record<string, Model
   return 'INT';
 }
 
-export function getTopologicalOrder(schemas: Record<string, ModelSchema>): string[] {
-  const visited = new Set<string>();
-  const order: string[] = [];
-
-  function visit(name: string): void {
-    if (visited.has(name)) return;
-    visited.add(name);
-
-    const schema = schemas[name];
-    if (!schema) return;
-
-    // Visit dependencies (belongsTo targets) first
-    for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
-      if (targetModelName) visit(targetModelName);
-    }
-
-    order.push(name);
-  }
-
-  for (const name of Object.keys(schemas)) {
-    visit(name);
-  }
-
-  return order;
-}
+export { getTopologicalOrder } from '../schema-helpers.js';
 
 export function introspectViews(): Record<string, ViewSchema> {
   const orm = (Orm as unknown as { instance: { views?: Record<string, unknown>; transforms: Record<string, unknown> } }).instance;

package/src/orm-request.ts

@@ -577,5 +577,6 @@ export default class OrmRequest extends Request {
     if (!access) return 403;
     if (Array.isArray(access) && !access.includes(methodAccessMap[request.method])) return 403;
     if (typeof access === 'function') state.filter = access;
+    return undefined;
   }
 }

package/src/postgres/migration-generator.ts

@@ -1,4 +1,5 @@
 import { introspectModels, introspectViews, buildTableDDL, buildViewDDL, buildVectorIndexDDL, schemasToSnapshot, viewSchemasToSnapshot, getTopologicalOrder } from './schema-introspector.js';
+import { buildCreateHypertable, buildEnableCompression, buildCompressionPolicy } from '../timescale/query-builder.js';
 import { readFile, createFile, createDirectory, fileExists } from '@stonyx/utils/file';
 import path from 'path';
 import config from 'stonyx/config';
@@ -97,6 +98,27 @@ export async function generateMigration(description: string = 'migration', confi
     downStatements.unshift(`DROP TABLE IF EXISTS "${schemas[name].table}" CASCADE;`);
   }
 
+  // Hypertable conversion + compression (TimescaleDB only)
+  if (configKey === 'timescale') {
+    for (const name of addedOrdered) {
+      const schema = schemas[name];
+      if (!schema.hypertable) continue;
+
+      const { timeColumn, chunkInterval } = schema.hypertable;
+      upStatements.push(buildCreateHypertable(schema.table, timeColumn, { chunkInterval }).sql + ';');
+
+      if (schema.hypertable.compress) {
+        const { segmentBy, orderBy, after } = schema.hypertable.compress;
+        upStatements.push(buildEnableCompression(schema.table, segmentBy, orderBy).sql + ';');
+        if (after) {
+          upStatements.push(buildCompressionPolicy(schema.table, after).sql + ';');
+        }
+      }
+
+      downStatements.unshift('-- Hypertable conversion is not reversible; table drop handles cleanup');
+    }
+  }
+
   // Removed tables (warn only, commented out)
   for (const name of diff.removedModels) {
     upStatements.push(`-- WARNING: Model '${name}' was removed. Uncomment to drop table:`);

package/src/postgres/schema-introspector.ts

@@ -4,14 +4,10 @@ import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from '../plural-registry.js';
 import { dbKey } from '../db.js';
 import { AggregateProperty } from '../aggregates.js';
-import type { ForeignKeyDef, ModelSchema, ViewSchema } from '../types/orm-types.js';
+import { getRelationshipInfo, sanitizeTableName } from '../schema-helpers.js';
+import type { ForeignKeyDef, HypertableConfig, ModelSchema, ViewSchema } from '../types/orm-types.js';
 import ModelProperty from '../model-property.js';
 
-interface RelationshipInfo {
-  type: 'belongsTo' | 'hasMany';
-  modelName: string | null;
-}
-
 interface ViewSnapshotEntry {
   viewName: string;
   source: string;
@@ -28,6 +24,7 @@ interface ModelSnapshotEntry {
   columns: Record<string, string>;
   foreignKeys: Record<string, ForeignKeyDef>;
   vectorColumns?: Record<string, number>;
+  hypertable?: HypertableConfig;
 }
 
 interface JoinDef {
@@ -35,21 +32,6 @@ interface JoinDef {
   condition: string;
 }
 
-function getRelationshipInfo(property: unknown): RelationshipInfo | null {
-  if (typeof property !== 'function') return null;
-  const relType = (property as { __relationshipType?: string }).__relationshipType;
-  const modelName = (property as { __relatedModelName?: string }).__relatedModelName || null;
-
-  if (relType === 'belongsTo') return { type: 'belongsTo', modelName };
-  if (relType === 'hasMany') return { type: 'hasMany', modelName };
-
-  return null;
-}
-
-function sanitizeTableName(name: string): string {
-  return name.replace(/[-/]/g, '_');
-}
-
 export function introspectModels(): Record<string, ModelSchema> {
   const { models } = Orm.instance as { models: Record<string, unknown> };
   const schemas: Record<string, ModelSchema> = {};
@@ -101,6 +83,8 @@ export function introspectModels(): Record<string, ModelSchema> {
       };
     }
 
+    const hypertable = (modelClass as { hypertable?: HypertableConfig }).hypertable;
+
     schemas[name] = {
       table: sanitizeTableName(getPluralName(name)),
       idType,
@@ -108,6 +92,7 @@ export function introspectModels(): Record<string, ModelSchema> {
       foreignKeys,
       relationships,
       vectorColumns,
+      hypertable: hypertable || undefined,
       memory: (modelClass as { memory?: boolean }).memory === true,
     };
   }
@@ -116,13 +101,16 @@ export function introspectModels(): Record<string, ModelSchema> {
 }
 
 export function buildTableDDL(name: string, schema: ModelSchema, allSchemas: Record<string, ModelSchema> = {}): string {
-  const { idType, columns, foreignKeys } = schema;
+  const { idType, columns, foreignKeys, hypertable } = schema;
   const table = sanitizeTableName(schema.table);
   const lines: string[] = [];
+  const useCompositePK = hypertable && idType !== 'string';
 
   // Primary key
   if (idType === 'string') {
     lines.push('  "id" VARCHAR(255) PRIMARY KEY');
+  } else if (useCompositePK) {
+    lines.push('  "id" INTEGER GENERATED ALWAYS AS IDENTITY');
   } else {
     lines.push('  "id" INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY');
   }
@@ -139,7 +127,11 @@ export function buildTableDDL(name: string, schema: ModelSchema, allSchemas: Rec
   }
 
   // Timestamps
-  lines.push('  "created_at" TIMESTAMPTZ DEFAULT NOW()');
+  if (useCompositePK) {
+    lines.push('  "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()');
+  } else {
+    lines.push('  "created_at" TIMESTAMPTZ DEFAULT NOW()');
+  }
   lines.push('  "updated_at" TIMESTAMPTZ DEFAULT NOW()');
 
   // Foreign key constraints
@@ -148,6 +140,11 @@ export function buildTableDDL(name: string, schema: ModelSchema, allSchemas: Rec
     lines.push(`  FOREIGN KEY ("${fkCol}") REFERENCES "${refTable}"("${fkDef.column}") ON DELETE SET NULL`);
   }
 
+  // Composite primary key for hypertable models
+  if (useCompositePK) {
+    lines.push(`  PRIMARY KEY ("id", "${hypertable.timeColumn}")`);
+  }
+
   return `CREATE TABLE IF NOT EXISTS "${table}" (\n${lines.join(',\n')}\n)`;
 }
 
@@ -177,31 +174,7 @@ function getReferencedIdType(tableName: string, allSchemas: Record<string, Model
   return 'INTEGER';
 }
 
-export function getTopologicalOrder(schemas: Record<string, ModelSchema>): string[] {
-  const visited = new Set<string>();
-  const order: string[] = [];
-
-  function visit(name: string): void {
-    if (visited.has(name)) return;
-    visited.add(name);
-
-    const schema = schemas[name];
-    if (!schema) return;
-
-    // Visit dependencies (belongsTo targets) first
-    for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
-      if (targetModelName) visit(targetModelName);
-    }
-
-    order.push(name);
-  }
-
-  for (const name of Object.keys(schemas)) {
-    visit(name);
-  }
-
-  return order;
-}
+export { getTopologicalOrder } from '../schema-helpers.js';
 
 export function introspectViews(): Record<string, ViewSchema> {
   const orm = Orm.instance as { views?: Record<string, unknown> };
@@ -379,6 +352,7 @@ export function schemasToSnapshot(schemas: Record<string, ModelSchema>): Record<
       ...(schema.vectorColumns && Object.keys(schema.vectorColumns).length > 0
         ? { vectorColumns: { ...schema.vectorColumns } }
         : {}),
+      ...(schema.hypertable ? { hypertable: schema.hypertable } : {}),
     };
   }
 

package/src/schema-helpers.ts

@@ -0,0 +1,59 @@
+import type { ModelSchema } from './types/orm-types.js';
+
+export interface SchemaRelationshipInfo {
+  type: 'belongsTo' | 'hasMany';
+  modelName: string | null;
+}
+
+/**
+ * Detect relationship type and target model from a model property function.
+ * Returns null if the property is not a relationship.
+ */
+export function getRelationshipInfo(property: unknown): SchemaRelationshipInfo | null {
+  if (typeof property !== 'function') return null;
+  const relType = (property as { __relationshipType?: string }).__relationshipType;
+  const modelName = (property as { __relatedModelName?: string }).__relatedModelName || null;
+
+  if (relType === 'belongsTo') return { type: 'belongsTo', modelName };
+  if (relType === 'hasMany') return { type: 'hasMany', modelName };
+
+  return null;
+}
+
+/**
+ * Sanitize a model/table name for use in SQL identifiers.
+ * Replaces hyphens and slashes with underscores.
+ */
+export function sanitizeTableName(name: string): string {
+  return name.replace(/[-/]/g, '_');
+}
+
+/**
+ * Sort model schemas in dependency order (belongsTo targets before dependents).
+ * Uses depth-first traversal to ensure referenced tables are created first.
+ */
+export function getTopologicalOrder(schemas: Record<string, ModelSchema>): string[] {
+  const visited = new Set<string>();
+  const order: string[] = [];
+
+  function visit(name: string): void {
+    if (visited.has(name)) return;
+    visited.add(name);
+
+    const schema = schemas[name];
+    if (!schema) return;
+
+    // Visit dependencies (belongsTo targets) first
+    for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
+      if (targetModelName) visit(targetModelName);
+    }
+
+    order.push(name);
+  }
+
+  for (const name of Object.keys(schemas)) {
+    visit(name);
+  }
+
+  return order;
+}

package/src/store.ts

@@ -185,14 +185,14 @@ export default class Store {
     const modelStore = this.data.get(model);
 
     if (!modelStore) {
-      console.warn(`[Store] Cannot unload record: model "${model}" not found in store`);
+      console.warn(`[Store] Cannot unload record: model "${model}" not found in store — ensure the model is registered before unloading`);
       return;
     }
 
     if (typeof id !== 'string' && typeof id !== 'number') return;
     const raw = modelStore.get(id);
     if (!raw || !isStoreRecord(raw)) {
-      console.warn(`[Store] Cannot unload record: ${model}:${id} not found in store`);
+      console.warn(`[Store] Cannot unload record: ${model}:${id} not found in store — it may have already been unloaded`);
       return;
     }
     const record = raw;
@@ -217,7 +217,7 @@ export default class Store {
     const modelStore = this.data.get(model);
 
     if (!modelStore) {
-      console.warn(`[Store] Cannot unload all records: model "${model}" not found in store`);
+      console.warn(`[Store] Cannot unload all records: model "${model}" not found in store — ensure the model is registered before unloading`);
       return;
     }
 

package/src/types/orm-types.ts

@@ -86,6 +86,16 @@ export interface ForeignKeyDef {
   column: string;
 }
 
+export interface HypertableConfig {
+  timeColumn: string;
+  chunkInterval?: string;
+  compress?: {
+    segmentBy?: string;
+    orderBy?: string;
+    after?: string;
+  };
+}
+
 export interface ModelSchema {
   table: string;
   idType: string;
@@ -96,6 +106,7 @@ export interface ModelSchema {
     hasMany: Record<string, string | null>;
   };
   vectorColumns?: Record<string, number>;
+  hypertable?: HypertableConfig;
   memory: boolean;
 }
 
@@ -139,6 +150,7 @@ export interface SnapshotEntry {
   columns?: Record<string, string>;
   foreignKeys?: Record<string, ForeignKeyDef>;
   vectorColumns?: Record<string, number>;
+  hypertable?: HypertableConfig;
   isView?: boolean;
   viewName?: string;
   source?: string;