@huluwz/pg-ethiopian-calendar 1.1.0 → 1.1.1

package/README.md

@@ -45,7 +45,9 @@ SELECT to_ethiopian_timestamp();                    -- '2018-04-23 14:30:00'
 SELECT ethiopian_calendar_version();                -- '1.1.0'
 ```
 
-## Generated Columns
+## Generated Columns (Timestamp)
+
+Use `to_ethiopian_timestamp()` for DateTime/Timestamp columns:
 
 ```sql
 CREATE TABLE orders (
@@ -56,17 +58,73 @@ CREATE TABLE orders (
 );
 ```
 
+For text format, use `to_ethiopian_date()`:
+
+```sql
+CREATE TABLE events (
+  id SERIAL PRIMARY KEY,
+  event_date TIMESTAMP NOT NULL,
+  event_date_ethiopian VARCHAR(10) GENERATED ALWAYS AS 
+    (to_ethiopian_date(event_date)) STORED
+);
+```
+
 ## With Prisma
 
+### Schema
+
+```prisma
+model Order {
+  id                 Int       @id @default(autoincrement())
+  createdAt          DateTime  @default(now()) @map("created_at")
+  createdAtEthiopian DateTime? @map("created_at_ethiopian")  // Generated column
+
+  @@map("orders")
+}
+```
+
+### ⚠️ Important: Migration Workflow
+
+Prisma doesn't natively support `GENERATED ALWAYS AS` columns. You must create migrations manually:
+
+```bash
+# ❌ DON'T do this - Prisma will generate wrong SQL
+npx prisma migrate dev
+
+# ✅ DO this instead - create empty migration, then edit
+npx prisma migrate dev --create-only --name add_orders_table
+```
+
+Then manually edit `migration.sql`:
+
+```sql
+CREATE TABLE "orders" (
+    "id" SERIAL PRIMARY KEY,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "created_at_ethiopian" TIMESTAMP(3) GENERATED ALWAYS AS 
+        (to_ethiopian_timestamp(created_at)) STORED
+);
+```
+
+Finally apply:
+
+```bash
+npx prisma migrate deploy
+```
+
+### Usage
+
 ```typescript
 const order = await prisma.order.create({
   data: { name: 'Test' }
 });
-console.log(order.createdAtEthiopian); // auto-populated
+console.log(order.createdAtEthiopian); // auto-populated DateTime!
 ```
 
 ## With Drizzle
 
+Drizzle has native support for generated columns:
+
 ```typescript
 import { sql } from 'drizzle-orm';
 
@@ -78,6 +136,29 @@ export const orders = pgTable('orders', {
 });
 ```
 
+## With TypeORM
+
+Use raw SQL in migrations:
+
+```typescript
+export class AddEthiopianCalendar1234567890 implements MigrationInterface {
+  async up(queryRunner: QueryRunner): Promise<void> {
+    // First, run the ethiopian calendar SQL from the package
+    await queryRunner.query(`/* ethiopian calendar functions */`);
+    
+    // Then create table with generated column
+    await queryRunner.query(`
+      CREATE TABLE "orders" (
+        "id" SERIAL PRIMARY KEY,
+        "created_at" TIMESTAMP DEFAULT NOW(),
+        "created_at_ethiopian" TIMESTAMP GENERATED ALWAYS AS 
+          (to_ethiopian_timestamp(created_at)) STORED
+      )
+    `);
+  }
+}
+```
+
 ## API
 
 ```typescript

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "1.1.0";
+export declare const VERSION = "1.1.1";
 export type SupportedORM = "prisma" | "drizzle" | "typeorm" | "raw";
 /** Returns the full SQL migration content */
 export declare function getSql(): string;

package/dist/index.js

@@ -13,7 +13,7 @@ exports.listMigrations = listMigrations;
 exports.getVersionCheckSql = getVersionCheckSql;
 const fs_1 = require("fs");
 const path_1 = require("path");
-exports.VERSION = "1.1.0";
+exports.VERSION = "1.1.1";
 const ORM_PACKAGES = {
     prisma: "@prisma/client",
     drizzle: "drizzle-orm",

package/docs/prisma.md

@@ -6,88 +6,126 @@
 # Install the package
 npm install @huluwz/pg-ethiopian-calendar
 
-# Generate migration
+# Generate migration for ethiopian calendar functions
 npx ethiopian-calendar init prisma
 
 # Apply migration
-npx prisma migrate dev
+npx prisma migrate deploy
 ```
 
-## Manual Setup
-
-If you prefer to set up manually:
+## Prisma Schema
 
-### 1. Create Migration Folder
+```prisma
+model Order {
+  id                 Int       @id @default(autoincrement())
+  customerName       String    @map("customer_name")
+  createdAt          DateTime  @default(now()) @map("created_at")
+  createdAtEthiopian DateTime? @map("created_at_ethiopian")  // Generated column
 
-```bash
-mkdir -p prisma/migrations/20240101000000_ethiopian_calendar
+  @@map("orders")
+}
 ```
 
-### 2. Copy SQL File
+**Note:** `createdAtEthiopian` must be optional (`DateTime?`) since Prisma only reads it—PostgreSQL generates it.
+
+## ⚠️ Important: Migration Workflow for Generated Columns
 
-Copy the SQL from `node_modules/@huluwz/pg-ethiopian-calendar/sql/ethiopian_calendar.sql` to `prisma/migrations/20240101000000_ethiopian_calendar/migration.sql`
+Prisma doesn't natively support PostgreSQL `GENERATED ALWAYS AS` columns. When adding tables with Ethiopian date columns, **do not run `prisma migrate dev` directly**.
 
-### 3. Apply Migration
+### The Problem
 
 ```bash
+# ❌ DON'T do this - Prisma will generate wrong SQL
 npx prisma migrate dev
 ```
 
-## Usage Examples
+Prisma sees `createdAtEthiopian DateTime?` and creates a regular nullable column, not a generated one.
 
-### Generated Columns
+### The Solution
 
-Create a table with automatically calculated Ethiopian dates:
+```bash
+# ✅ Step 1: Create empty migration
+npx prisma migrate dev --create-only --name add_orders_table
+```
+
+```bash
+# ✅ Step 2: Edit the generated migration.sql manually
+```
+
+Replace Prisma's generated SQL with:
 
 ```sql
--- In your migration file
-CREATE TABLE orders (
-    id SERIAL PRIMARY KEY,
-    customer_name TEXT NOT NULL,
-    created_at TIMESTAMP DEFAULT NOW(),
-    created_at_ethiopian TIMESTAMP GENERATED ALWAYS AS 
+CREATE TABLE "orders" (
+    "id" SERIAL PRIMARY KEY,
+    "customer_name" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "created_at_ethiopian" TIMESTAMP(3) GENERATED ALWAYS AS 
         (to_ethiopian_timestamp(created_at)) STORED
 );
 ```
 
-### Prisma Schema
+```bash
+# ✅ Step 3: Apply the migration
+npx prisma migrate deploy
+```
+
+## Generated Column Types
+
+### Timestamp (Recommended)
+
+Preserves full date and time:
+
+```sql
+"created_at_ethiopian" TIMESTAMP(3) GENERATED ALWAYS AS 
+    (to_ethiopian_timestamp(created_at)) STORED
+```
 
 ```prisma
-model Order {
-  id                   Int       @id @default(autoincrement())
-  customerName         String    @map("customer_name")
-  createdAt            DateTime  @default(now()) @map("created_at")
-  createdAtEthiopian   DateTime  @map("created_at_ethiopian")
+createdAtEthiopian DateTime? @map("created_at_ethiopian")
+```
 
-  @@map("orders")
-}
+Result: `2018-04-26T12:30:00.000Z`
+
+### Text/String
+
+Date-only format:
+
+```sql
+"created_at_ethiopian" VARCHAR(10) GENERATED ALWAYS AS 
+    (to_ethiopian_date(created_at)) STORED
 ```
 
-**Note:** `createdAtEthiopian` is read-only (generated by database). Don't include it in `create` or `update` operations.
+```prisma
+createdAtEthiopian String? @map("created_at_ethiopian") @db.VarChar(10)
+```
 
-### Using in Code
+Result: `"2018-04-26"`
+
+## Usage in Code
 
 ```typescript
 import { PrismaClient } from '@prisma/client'
 
 const prisma = new PrismaClient()
 
-// Create - Ethiopian date is auto-generated
+// Create - Ethiopian date is auto-generated by PostgreSQL
 const order = await prisma.order.create({
   data: {
     customerName: 'Abebe Kebede',
   }
 })
 
-console.log(order.createdAtEthiopian) // Ethiopian timestamp!
+console.log(order.createdAt)          // 2026-01-04T12:30:00.000Z (Gregorian)
+console.log(order.createdAtEthiopian) // 2018-04-26T12:30:00.000Z (Ethiopian)
 
-// Raw query
-const today = await prisma.$queryRaw`
-  SELECT current_ethiopian_date() as today
-`
+// Raw queries for calendar utilities
+const today = await prisma.$queryRaw`SELECT to_ethiopian_date()`
+const converted = await prisma.$queryRaw`SELECT from_ethiopian_date('2018-04-26')`
 ```
 
-### Functional Index
+## Functional Index
+
+For fast queries by Ethiopian date:
 
 ```sql
 CREATE INDEX idx_orders_ethiopian 
@@ -98,31 +136,34 @@ ON orders (to_ethiopian_date(created_at));
 
 | Function | Description |
 |----------|-------------|
+| `to_ethiopian_date()` | Current Ethiopian date as text |
 | `to_ethiopian_date(timestamp)` | Convert to Ethiopian date string (YYYY-MM-DD) |
 | `from_ethiopian_date(text)` | Convert Ethiopian date to Gregorian timestamp |
+| `to_ethiopian_timestamp()` | Current Ethiopian timestamp |
 | `to_ethiopian_timestamp(timestamp)` | Convert preserving time (for generated columns) |
-| `current_ethiopian_date()` | Get current Ethiopian date |
+| `ethiopian_calendar_version()` | Package version |
 
 ## Troubleshooting
 
 ### Migration Already Exists
 
-If you get an error about the migration already existing:
-
 ```bash
 npx prisma migrate resolve --applied 20240101000000_ethiopian_calendar
 ```
 
 ### Functions Not Found
 
-Make sure the migration was applied:
+Check migration status:
 
 ```bash
 npx prisma migrate status
 ```
 
+### Prisma Tries to "Fix" Generated Columns
+
+If Prisma shows a migration to alter your generated columns, cancel it. The schema is correct—Prisma just doesn't understand generated columns.
+
 ## Links
 
 - [GitHub Repository](https://github.com/HuluWZ/pg-ethiopian-calendar)
 - [NPM Package](https://www.npmjs.com/package/@huluwz/pg-ethiopian-calendar)
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huluwz/pg-ethiopian-calendar",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Ethiopian calendar functions for PostgreSQL - works with Prisma, Drizzle, TypeORM",
   "author": "Hulunlante Worku <hulunlante.w@gmail.com>",
   "license": "PostgreSQL",