@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/guides/tutorials/ecommerce-api.md

@@ -28,7 +28,7 @@ cd ecommerce-api
 bun init -y
 
 # Install dependencies
-bun add hono @hono/zod-openapi @venizia/ignis @venizia/ignis-helpers
+bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis @venizia/ignis-helpers
 bun add drizzle-orm drizzle-zod pg stripe
 bun add -d typescript @types/bun @venizia/dev-configs drizzle-kit @types/pg
 ```
@@ -85,10 +85,11 @@ Models in IGNIS combine Drizzle ORM schemas with Entity classes.
 // src/models/category.model.ts
 import {
   BaseEntity,
-  createRelations,
   generateIdColumnDefs,
   generateTzColumnDefs,
   model,
+  RelationTypes,
+  TRelationConfig,
   TTableObject,
 } from '@venizia/ignis';
 import { pgTable, text, varchar } from 'drizzle-orm/pg-core';
@@ -102,21 +103,28 @@ export const categoryTable = pgTable('Category', {
   parentId: text('parent_id'),
 });
 
-export const categoryRelations = createRelations({
-  source: categoryTable,
-  relations: [
-    { type: 'one', name: 'parent', target: () => categoryTable, fields: ['parentId'], references: ['id'] },
-    { type: 'many', name: 'children', target: () => categoryTable, fields: ['id'], references: ['parentId'] },
-  ],
-});
-
 export type TCategorySchema = typeof categoryTable;
 export type TCategory = TTableObject<TCategorySchema>;
 
 @model({ type: 'entity' })
 export class Category extends BaseEntity<typeof Category.schema> {
   static override schema = categoryTable;
-  static override relations = () => categoryRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'parent',
+      type: RelationTypes.ONE,
+      schema: categoryTable,
+      metadata: { fields: [categoryTable.parentId], references: [categoryTable.id] },
+    },
+    {
+      name: 'children',
+      type: RelationTypes.MANY,
+      schema: categoryTable,
+      metadata: { fields: [categoryTable.id], references: [categoryTable.parentId] },
+    },
+  ];
+
   static override TABLE_NAME = 'Category';
 }
 ```
@@ -127,14 +135,15 @@ export class Category extends BaseEntity<typeof Category.schema> {
 // src/models/product.model.ts
 import {
   BaseEntity,
-  createRelations,
   generateIdColumnDefs,
   generateTzColumnDefs,
   model,
+  RelationTypes,
+  TRelationConfig,
   TTableObject,
 } from '@venizia/ignis';
 import { pgTable, text, varchar, decimal, integer, boolean } from 'drizzle-orm/pg-core';
-import { categoryTable, Category } from './category.model';
+import { categoryTable } from './category.model';
 
 export const productTable = pgTable('Product', {
   ...generateIdColumnDefs({ id: { dataType: 'string' } }),
@@ -150,20 +159,22 @@ export const productTable = pgTable('Product', {
   imageUrl: text('image_url'),
 });
 
-export const productRelations = createRelations({
-  source: productTable,
-  relations: [
-    { type: 'one', name: 'category', target: () => categoryTable, fields: ['categoryId'], references: ['id'] },
-  ],
-});
-
 export type TProductSchema = typeof productTable;
 export type TProduct = TTableObject<TProductSchema>;
 
 @model({ type: 'entity' })
 export class Product extends BaseEntity<typeof Product.schema> {
   static override schema = productTable;
-  static override relations = () => productRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'category',
+      type: RelationTypes.ONE,
+      schema: categoryTable,
+      metadata: { fields: [productTable.categoryId], references: [categoryTable.id] },
+    },
+  ];
+
   static override TABLE_NAME = 'Product';
 }
 ```
@@ -174,10 +185,11 @@ export class Product extends BaseEntity<typeof Product.schema> {
 // src/models/cart.model.ts
 import {
   BaseEntity,
-  createRelations,
   generateIdColumnDefs,
   generateTzColumnDefs,
   model,
+  RelationTypes,
+  TRelationConfig,
   TTableObject,
 } from '@venizia/ignis';
 import { pgTable, text, varchar, integer } from 'drizzle-orm/pg-core';
@@ -198,21 +210,6 @@ export const cartItemTable = pgTable('CartItem', {
   quantity: integer('quantity').default(1).notNull(),
 });
 
-export const cartRelations = createRelations({
-  source: cartTable,
-  relations: [
-    { type: 'many', name: 'items', target: () => cartItemTable, fields: ['id'], references: ['cartId'] },
-  ],
-});
-
-export const cartItemRelations = createRelations({
-  source: cartItemTable,
-  relations: [
-    { type: 'one', name: 'cart', target: () => cartTable, fields: ['cartId'], references: ['id'] },
-    { type: 'one', name: 'product', target: () => productTable, fields: ['productId'], references: ['id'] },
-  ],
-});
-
 export type TCartSchema = typeof cartTable;
 export type TCart = TTableObject<TCartSchema>;
 export type TCartItemSchema = typeof cartItemTable;
@@ -221,14 +218,38 @@ export type TCartItem = TTableObject<TCartItemSchema>;
 @model({ type: 'entity' })
 export class Cart extends BaseEntity<typeof Cart.schema> {
   static override schema = cartTable;
-  static override relations = () => cartRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'items',
+      type: RelationTypes.MANY,
+      schema: cartItemTable,
+      metadata: { fields: [cartTable.id], references: [cartItemTable.cartId] },
+    },
+  ];
+
   static override TABLE_NAME = 'Cart';
 }
 
 @model({ type: 'entity' })
 export class CartItem extends BaseEntity<typeof CartItem.schema> {
   static override schema = cartItemTable;
-  static override relations = () => cartItemRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'cart',
+      type: RelationTypes.ONE,
+      schema: cartTable,
+      metadata: { fields: [cartItemTable.cartId], references: [cartTable.id] },
+    },
+    {
+      name: 'product',
+      type: RelationTypes.ONE,
+      schema: productTable,
+      metadata: { fields: [cartItemTable.productId], references: [productTable.id] },
+    },
+  ];
+
   static override TABLE_NAME = 'CartItem';
 }
 ```
@@ -239,10 +260,11 @@ export class CartItem extends BaseEntity<typeof CartItem.schema> {
 // src/models/order.model.ts
 import {
   BaseEntity,
-  createRelations,
   generateIdColumnDefs,
   generateTzColumnDefs,
   model,
+  RelationTypes,
+  TRelationConfig,
   TTableObject,
 } from '@venizia/ignis';
 import { pgTable, text, varchar, decimal, integer, jsonb } from 'drizzle-orm/pg-core';
@@ -272,21 +294,6 @@ export const orderItemTable = pgTable('OrderItem', {
   quantity: integer('quantity').notNull(),
 });
 
-export const orderRelations = createRelations({
-  source: orderTable,
-  relations: [
-    { type: 'many', name: 'items', target: () => orderItemTable, fields: ['id'], references: ['orderId'] },
-  ],
-});
-
-export const orderItemRelations = createRelations({
-  source: orderItemTable,
-  relations: [
-    { type: 'one', name: 'order', target: () => orderTable, fields: ['orderId'], references: ['id'] },
-    { type: 'one', name: 'product', target: () => productTable, fields: ['productId'], references: ['id'] },
-  ],
-});
-
 export type TOrderSchema = typeof orderTable;
 export type TOrder = TTableObject<TOrderSchema>;
 export type TOrderItemSchema = typeof orderItemTable;
@@ -295,14 +302,38 @@ export type TOrderItem = TTableObject<TOrderItemSchema>;
 @model({ type: 'entity' })
 export class Order extends BaseEntity<typeof Order.schema> {
   static override schema = orderTable;
-  static override relations = () => orderRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'items',
+      type: RelationTypes.MANY,
+      schema: orderItemTable,
+      metadata: { fields: [orderTable.id], references: [orderItemTable.orderId] },
+    },
+  ];
+
   static override TABLE_NAME = 'Order';
 }
 
 @model({ type: 'entity' })
 export class OrderItem extends BaseEntity<typeof OrderItem.schema> {
   static override schema = orderItemTable;
-  static override relations = () => orderItemRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'order',
+      type: RelationTypes.ONE,
+      schema: orderTable,
+      metadata: { fields: [orderItemTable.orderId], references: [orderTable.id] },
+    },
+    {
+      name: 'product',
+      type: RelationTypes.ONE,
+      schema: productTable,
+      metadata: { fields: [orderItemTable.productId], references: [productTable.id] },
+    },
+  ];
+
   static override TABLE_NAME = 'OrderItem';
 }
 ```
@@ -326,7 +357,7 @@ import {
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -337,7 +368,7 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -353,16 +384,18 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
+    const schema = Object.keys(this.getSchema());
 
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
-      Object.keys(schema).length,
-      Object.keys(schema),
+      schema.length,
+      schema,
     );
 
-    const client = new Pool(this.settings);
-    this.connector = drizzle({ client, schema });
+    // The client must land on this.client - a local would leave beginTransaction() with nothing
+    // to resolve a driver from, and it would throw `No driver and no client`. NodePostgresDriver
+    // named in @datasource above is what wires the driver and Drizzle connector from it.
+    this.client = new Pool(this.settings);
   }
 }
 ```
@@ -420,24 +453,25 @@ export class CartRepository extends DefaultCRUDRepository<typeof Cart.schema> {
 
   async findCartItem(opts: { cartId: string; productId: string }) {
     return this._cartItemRepo.findOne({
-      where: { cartId: opts.cartId, productId: opts.productId },
+      filter: { where: { cartId: opts.cartId, productId: opts.productId } },
     });
   }
 
   async addCartItem(opts: { cartId: string; productId: string; quantity: number }) {
-    return this._cartItemRepo.create(opts);
+    const rs = await this._cartItemRepo.create({ data: opts });
+    return rs.data;
   }
 
   async updateCartItem(opts: { itemId: string; data: { quantity: number } }) {
-    return this._cartItemRepo.updateById(opts.itemId, opts.data);
+    return this._cartItemRepo.updateById({ id: opts.itemId, data: opts.data });
   }
 
   async deleteCartItem(opts: { itemId: string }) {
-    return this._cartItemRepo.deleteById(opts.itemId);
+    return this._cartItemRepo.deleteById({ id: opts.itemId });
   }
 
   async getCartItems(opts: { cartId: string }) {
-    return this._cartItemRepo.find({ where: { cartId: opts.cartId } });
+    return this._cartItemRepo.find({ filter: { where: { cartId: opts.cartId } } });
   }
 
   async clearCart(opts: { cartId: string }) {
@@ -478,11 +512,12 @@ export class OrderRepository extends DefaultCRUDRepository<typeof Order.schema>
     price: string;
     quantity: number;
   }) {
-    return this._orderItemRepo.create(opts);
+    const rs = await this._orderItemRepo.create({ data: opts });
+    return rs.data;
   }
 
   async getOrderItems(opts: { orderId: string }) {
-    return this._orderItemRepo.find({ where: { orderId: opts.orderId } });
+    return this._orderItemRepo.find({ filter: { where: { orderId: opts.orderId } } });
   }
 }
 ```
@@ -496,7 +531,7 @@ import { BaseService } from '@venizia/ignis';
 import { ProductRepository } from '../repositories/product.repository';
 import { getError } from '@venizia/ignis-helpers';
 
-@injectable()
+@injectable({})
 export class ProductService extends BaseService {
   constructor(
     @inject({ key: 'repositories.ProductRepository' })
@@ -507,18 +542,20 @@ export class ProductService extends BaseService {
 
   async getActiveProducts(opts: { categoryId?: string; limit?: number; offset?: number }) {
     return this._productRepo.find({
-      where: {
-        isActive: true,
-        ...(opts.categoryId && { categoryId: opts.categoryId }),
+      filter: {
+        where: {
+          isActive: true,
+          ...(opts.categoryId && { categoryId: opts.categoryId }),
+        },
+        order: ['createdAt DESC'],
+        limit: opts.limit ?? 20,
+        offset: opts.offset ?? 0,
       },
-      orderBy: { createdAt: 'desc' },
-      limit: opts.limit ?? 20,
-      offset: opts.offset ?? 0,
     });
   }
 
   async getProductById(opts: { id: string }) {
-    const product = await this._productRepo.findById(opts.id);
+    const product = await this._productRepo.findById({ id: opts.id });
     if (!product) {
       throw getError({ statusCode: 404, message: 'Product not found' });
     }
@@ -540,16 +577,16 @@ export class ProductService extends BaseService {
       });
     }
 
-    await this._productRepo.updateById(opts.productId, {
+    await this._productRepo.updateById({ id: opts.productId, data: {
       stock: product.stock - opts.quantity,
-    });
+    } });
   }
 
   async releaseStock(opts: { productId: string; quantity: number }) {
     const product = await this.getProductById({ id: opts.productId });
-    await this._productRepo.updateById(opts.productId, {
+    await this._productRepo.updateById({ id: opts.productId, data: {
       stock: product.stock + opts.quantity,
-    });
+    } });
   }
 }
 ```
@@ -569,7 +606,7 @@ interface ICartItem {
   quantity: number;
 }
 
-@injectable()
+@injectable({})
 export class CartService extends BaseService {
   constructor(
     @inject({ key: 'repositories.CartRepository' })
@@ -583,16 +620,14 @@ export class CartService extends BaseService {
   async getOrCreateCart(opts: { userId?: string; sessionId?: string }) {
     // Try to find existing cart
     let cart = await this._cartRepo.findOne({
-      where: opts.userId
+      filter: { where: opts.userId
         ? { userId: opts.userId }
-        : { sessionId: opts.sessionId },
+        : { sessionId: opts.sessionId } },
     });
 
     if (!cart) {
-      cart = await this._cartRepo.create({
-        userId: opts.userId,
-        sessionId: opts.sessionId,
-      });
+      const rs = await this._cartRepo.create({ data: { userId: opts.userId, sessionId: opts.sessionId } });
+      cart = rs.data;
     }
 
     return cart;
@@ -657,7 +692,7 @@ export class CartService extends BaseService {
   }
 
   async getCartWithItems(opts: { cartId: string }) {
-    const cart = await this._cartRepo.findById(opts.cartId);
+    const cart = await this._cartRepo.findById({ id: opts.cartId });
     if (!cart) {
       throw getError({ statusCode: 404, message: 'Cart not found' });
     }
@@ -706,22 +741,24 @@ import { ProductService } from './product.service';
 import { PaymentService } from './payment.service';
 import { getError } from '@venizia/ignis-helpers';
 
+interface IOrderAddress {
+  name: string;
+  line1: string;
+  line2?: string;
+  city: string;
+  state: string;
+  postalCode: string;
+  country: string;
+}
+
 interface ICreateOrderInput {
   cartId: string;
   email: string;
-  shippingAddress: {
-    name: string;
-    line1: string;
-    line2?: string;
-    city: string;
-    state: string;
-    postalCode: string;
-    country: string;
-  };
-  billingAddress?: typeof shippingAddress;
+  shippingAddress: IOrderAddress;
+  billingAddress?: IOrderAddress;
 }
 
-@injectable()
+@injectable({})
 export class OrderService extends BaseService {
   constructor(
     @inject({ key: 'repositories.OrderRepository' })
@@ -769,13 +806,13 @@ export class OrderService extends BaseService {
       amount: Math.round(total * 100), // Stripe uses cents
       currency: 'usd',
       metadata: {
-        cartId: input.cartId,
-        email: input.email,
+        cartId: opts.input.cartId,
+        email: opts.input.email,
       },
     });
 
     // Create order
-    const order = await this._orderRepo.create({
+    const { data: order } = await this._orderRepo.create({ data: {
       email: opts.input.email,
       status: 'pending_payment',
       subtotal: subtotal.toString(),
@@ -785,7 +822,7 @@ export class OrderService extends BaseService {
       shippingAddress: opts.input.shippingAddress,
       billingAddress: opts.input.billingAddress ?? opts.input.shippingAddress,
       paymentIntentId: paymentIntent.id,
-    });
+    } });
 
     // Create order items
     for (const item of cart.items) {
@@ -805,7 +842,7 @@ export class OrderService extends BaseService {
   }
 
   async confirmPayment(opts: { orderId: string; paymentIntentId: string }) {
-    const order = await this._orderRepo.findById(opts.orderId);
+    const order = await this._orderRepo.findById({ id: opts.orderId });
 
     if (!order) {
       throw getError({ statusCode: 404, message: 'Order not found' });
@@ -823,7 +860,7 @@ export class OrderService extends BaseService {
     }
 
     // Update order status
-    await this._orderRepo.updateById(opts.orderId, { status: 'paid' });
+    await this._orderRepo.updateById({ id: opts.orderId, data: { status: 'paid' } });
 
     // Reserve stock for all items
     const orderItems = await this._orderRepo.getOrderItems({ orderId: opts.orderId });
@@ -831,18 +868,20 @@ export class OrderService extends BaseService {
       await this._productService.reserveStock({ productId: item.productId, quantity: item.quantity });
     }
 
-    return this._orderRepo.findById(opts.orderId);
+    return this._orderRepo.findById({ id: opts.orderId });
   }
 
   async getOrdersByUser(opts: { userId: string }) {
     return this._orderRepo.find({
-      where: { userId: opts.userId },
-      orderBy: { createdAt: 'desc' },
+      filter: {
+        where: { userId: opts.userId },
+        order: ['createdAt DESC'],
+      },
     });
   }
 
   async getOrderById(opts: { orderId: string }) {
-    const order = await this._orderRepo.findById(opts.orderId);
+    const order = await this._orderRepo.findById({ id: opts.orderId });
     if (!order) {
       throw getError({ statusCode: 404, message: 'Order not found' });
     }
@@ -858,7 +897,7 @@ export class OrderService extends BaseService {
       throw getError({ statusCode: 400, message: 'Invalid status' });
     }
 
-    return this._orderRepo.updateById(opts.orderId, { status: opts.status });
+    return this._orderRepo.updateById({ id: opts.orderId, data: { status: opts.status } });
   }
 }
 ```
@@ -870,16 +909,16 @@ export class OrderService extends BaseService {
 import { injectable } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import Stripe from 'stripe';
-import { EnvHelper } from '@venizia/ignis-helpers';
+import { applicationEnvironment } from '@venizia/ignis-helpers';
 
-@injectable()
+@injectable({})
 export class PaymentService extends BaseService {
   private _stripe: Stripe;
 
   constructor() {
     super({ scope: PaymentService.name });
 
-    const secretKey = EnvHelper.get('APP_ENV_STRIPE_SECRET_KEY');
+    const secretKey = applicationEnvironment.get<string>('APP_ENV_STRIPE_SECRET_KEY');
     this._stripe = new Stripe(secretKey, {
       apiVersion: '2023-10-16',
     });
@@ -913,7 +952,7 @@ export class PaymentService extends BaseService {
   }
 
   async createWebhookEvent(opts: { payload: string; signature: string }) {
-    const webhookSecret = EnvHelper.get('APP_ENV_STRIPE_WEBHOOK_SECRET');
+    const webhookSecret = applicationEnvironment.get<string>('APP_ENV_STRIPE_WEBHOOK_SECRET');
     return this._stripe.webhooks.constructEvent(opts.payload, opts.signature, webhookSecret);
   }
 }
@@ -961,7 +1000,7 @@ const ProductRoutes = {
   },
   GET_BY_ID: {
     method: HTTP.Methods.GET,
-    path: '/:id',
+    path: '/{id}',
     request: {
       params: z.object({ id: z.string().uuid() }),
     },
@@ -1059,7 +1098,7 @@ const CartRoutes = {
   },
   UPDATE_ITEM: {
     method: HTTP.Methods.PUT,
-    path: '/items/:productId',
+    path: '/items/{productId}',
     request: {
       params: z.object({ productId: z.string().uuid() }),
       body: jsonContent({
@@ -1077,7 +1116,7 @@ const CartRoutes = {
   },
   REMOVE_ITEM: {
     method: HTTP.Methods.DELETE,
-    path: '/items/:productId',
+    path: '/items/{productId}',
     request: {
       params: z.object({ productId: z.string().uuid() }),
     },
@@ -1198,7 +1237,7 @@ const OrderRoutes = {
   },
   CONFIRM: {
     method: HTTP.Methods.POST,
-    path: '/:id/confirm',
+    path: '/{id}/confirm',
     request: {
       params: z.object({ id: z.string().uuid() }),
       body: jsonContent({
@@ -1216,7 +1255,7 @@ const OrderRoutes = {
   },
   GET_BY_ID: {
     method: HTTP.Methods.GET,
-    path: '/:id',
+    path: '/{id}',
     request: {
       params: z.object({ id: z.string().uuid() }),
     },
@@ -1272,7 +1311,7 @@ export class OrderController extends BaseRestController {
 ```typescript
 // src/application.ts
 import { BaseApplication, IApplicationInfo } from '@venizia/ignis';
-import { HealthCheckComponent, SwaggerComponent } from '@venizia/ignis';
+import { HealthCheckComponent, ApiReferenceComponent } from '@venizia/ignis';
 
 import { ProductController } from './controllers/product';
 import { CartController } from './controllers/cart';
@@ -1318,7 +1357,7 @@ export class EcommerceApp extends BaseApplication {
 
     // Components
     this.component(HealthCheckComponent);
-    this.component(SwaggerComponent);
+    this.component(ApiReferenceComponent);
   }
 
   postConfigure() {}