@shetty4l/core 0.1.36 → 0.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shetty4l/core",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Shared infrastructure primitives for Bun/TypeScript services",
   "repository": {
     "type": "git",

package/src/state/collection/decorators.ts

@@ -192,10 +192,21 @@ export function Id(type: FieldType = "string", options?: IdOptions) {
  *
  * @param type - The field type ('string' | 'number' | 'boolean' | 'date')
  * @param options - Optional field configuration (column name override)
+ * @throws Error if property name is a reserved timestamp field (created_at, updated_at)
  */
 export function Field(type: FieldType, options?: FieldOptions) {
   return function (_target: undefined, context: unknown): void {
     const property = extractPropertyName(context);
+
+    // Reject reserved timestamp field names
+    if (property === "created_at" || property === "updated_at") {
+      resetGlobalState();
+      throw new Error(
+        `"${property}" is reserved for auto-managed timestamps. ` +
+          `Remove the @Field decorator - timestamps are automatically populated by StateLoader.`,
+      );
+    }
+
     const column = options?.column ?? toSnakeCase(property);
 
     // Accumulate field definitions

package/src/state/collection/query.ts

@@ -50,16 +50,35 @@ function getColumn(meta: CollectionMeta, property: string): string {
     return meta.idColumn;
   }
 
+  // Handle auto-managed timestamp fields
+  if (property === "created_at") {
+    return "created_at";
+  }
+  if (property === "updated_at") {
+    return "updated_at";
+  }
+
   const field = meta.fields.get(property);
   if (!field) {
     throw new Error(
       `Property "${property}" not found in collection "${meta.table}". ` +
-        `Available fields: ${meta.idProperty}, ${[...meta.fields.keys()].join(", ")}`,
+        `Available fields: ${meta.idProperty}, ${[...meta.fields.keys()].join(", ")}, created_at, updated_at`,
     );
   }
   return field.column;
 }
 
+/**
+ * Serialize a value for SQL binding.
+ * Converts Date objects to ISO strings, passes other values through.
+ */
+function serializeBindValue(value: unknown): SQLQueryBindings {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return value as SQLQueryBindings;
+}
+
 /**
  * Build SQL condition fragment and params for a single operator.
  *
@@ -75,41 +94,47 @@ function buildOperatorCondition(
 ): { sql: string; params: SQLQueryBindings[] } {
   switch (op) {
     case "eq":
-      return { sql: `${column} = ?`, params: [value as SQLQueryBindings] };
+      return { sql: `${column} = ?`, params: [serializeBindValue(value)] };
 
     case "neq":
-      return { sql: `${column} != ?`, params: [value as SQLQueryBindings] };
+      return { sql: `${column} != ?`, params: [serializeBindValue(value)] };
 
     case "lt":
-      return { sql: `${column} < ?`, params: [value as SQLQueryBindings] };
+      return { sql: `${column} < ?`, params: [serializeBindValue(value)] };
 
     case "lte":
-      return { sql: `${column} <= ?`, params: [value as SQLQueryBindings] };
+      return { sql: `${column} <= ?`, params: [serializeBindValue(value)] };
 
     case "gt":
-      return { sql: `${column} > ?`, params: [value as SQLQueryBindings] };
+      return { sql: `${column} > ?`, params: [serializeBindValue(value)] };
 
     case "gte":
-      return { sql: `${column} >= ?`, params: [value as SQLQueryBindings] };
+      return { sql: `${column} >= ?`, params: [serializeBindValue(value)] };
 
     case "in": {
-      const arr = value as SQLQueryBindings[];
+      const arr = value as unknown[];
       if (!Array.isArray(arr) || arr.length === 0) {
         // Empty IN clause: always false
         return { sql: "0 = 1", params: [] };
       }
       const placeholders = arr.map(() => "?").join(", ");
-      return { sql: `${column} IN (${placeholders})`, params: arr };
+      return {
+        sql: `${column} IN (${placeholders})`,
+        params: arr.map(serializeBindValue),
+      };
     }
 
     case "notIn": {
-      const arr = value as SQLQueryBindings[];
+      const arr = value as unknown[];
       if (!Array.isArray(arr) || arr.length === 0) {
         // Empty NOT IN clause: always true (no exclusions)
         return { sql: "1 = 1", params: [] };
       }
       const placeholders = arr.map(() => "?").join(", ");
-      return { sql: `${column} NOT IN (${placeholders})`, params: arr };
+      return {
+        sql: `${column} NOT IN (${placeholders})`,
+        params: arr.map(serializeBindValue),
+      };
     }
 
     case "isNull":

package/src/state/collection/types.ts

@@ -128,6 +128,10 @@ export interface FindOptions<T> {
  * from singleton @Persisted classes. Subclasses must be decorated with
  * @PersistedCollection.
  *
+ * Auto-managed timestamps (`created_at`, `updated_at`) are populated when
+ * entities are loaded from the database. These are read-only and cannot be
+ * set via @Field decorators.
+ *
  * @example
  * ```ts
  * @PersistedCollection('users')
@@ -143,9 +147,34 @@ export interface FindOptions<T> {
  *     // Implemented by StateLoader binding
  *   }
  * }
+ *
+ * // Usage: timestamps are available after load
+ * const user = loader.get(User, 'abc123');
+ * console.log(user.created_at); // Date when entity was created
+ * console.log(user.updated_at); // Date when entity was last modified
+ *
+ * // Query by timestamps
+ * const recent = loader.find(User, {
+ *   where: { updated_at: { op: 'gte', value: yesterday } },
+ *   orderBy: { created_at: 'desc' }
+ * });
  * ```
  */
 export abstract class CollectionEntity {
+  /**
+   * Timestamp when this entity was first created.
+   * Auto-managed by StateLoader; populated on load.
+   * Default value before population is epoch (1970-01-01).
+   */
+  readonly created_at: Date = new Date(0);
+
+  /**
+   * Timestamp when this entity was last modified.
+   * Auto-managed by StateLoader; updated on every save().
+   * Default value before population is epoch (1970-01-01).
+   */
+  readonly updated_at: Date = new Date(0);
+
   /**
    * Persist this entity to the database.
    * Implemented when the entity is bound to a StateLoader.

package/src/state/index.ts

@@ -65,8 +65,14 @@ export { Field, Persisted } from "./decorators";
 
 /** Mark a class as a persisted collection (multi-row table). */
 /** Mark a property as the primary key field. */
+/** Mark a property as a persisted field in a collection (use with @PersistedCollection). */
 /** Mark column(s) for indexing. */
-export { Id, Index, PersistedCollection } from "./collection/decorators";
+export {
+  Field as CollectionField,
+  Id,
+  Index,
+  PersistedCollection,
+} from "./collection/decorators";
 
 // --------------------------------------------------------------------------
 // Collection base class

package/src/state/loader.ts

@@ -753,6 +753,19 @@ export class StateLoader {
         (instance as Record<string, unknown>)[field.property] = value;
       }
     }
+
+    // Set auto-managed timestamps
+    const rawCreatedAt = row.created_at;
+    if (rawCreatedAt !== null && rawCreatedAt !== undefined) {
+      const createdAtValue = deserializeValue(rawCreatedAt, "date");
+      (instance as Record<string, unknown>).created_at = createdAtValue;
+    }
+
+    const rawUpdatedAt = row.updated_at;
+    if (rawUpdatedAt !== null && rawUpdatedAt !== undefined) {
+      const updatedAtValue = deserializeValue(rawUpdatedAt, "date");
+      (instance as Record<string, unknown>).updated_at = updatedAtValue;
+    }
   }
 
   /**