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

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

@@ -21,9 +21,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 = {};
@@ -129,28 +116,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)

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/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.90",
+  "version": "0.2.1-beta.91",
   "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/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 { getRelationshipInfo, sanitizeTableName } from '../schema-helpers.js';
 import type { ForeignKeyDef, 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;
@@ -35,21 +31,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> = {};
@@ -177,31 +158,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> };

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;
     }