@akanjs/cli 0.0.142 → 0.0.144

package/src/guidelines/databaseModule/databaseModule.instruction.md

@@ -0,0 +1,691 @@
+# Database Module in Akan.js
+
+## Purpose of Database Modules
+
+Database modules in Akan.js provide a structured approach to building domain-specific features with seamless integration between server and client:
+
+1. **Domain Encapsulation**: Encapsulate all domain-specific logic (models, services, signals) in a consistent structure
+2. **Full-Stack Integration**: Enable seamless integration between MongoDB, NestJS server, and React client
+3. **Type Safety**: Ensure type safety across the entire stack with auto-generated GraphQL types
+4. **Automated CRUD**: Provide automatic CRUD operations through standardized patterns
+5. **Real-time Capabilities**: Support for websockets, GraphQL subscriptions, and background processing
+6. **Security**: Implement role-based access control and validation at every level
+
+## File Structure and Location Conventions
+
+A complete database module follows this structure:
+
+```
+libs/shared/lib/[module-name]/
+├── [ModuleName].Template.tsx      // Form components
+├── [ModuleName].Unit.tsx          // Card/list view components
+├── [ModuleName].Util.tsx          // Utility components (dashboard, insights)
+├── [ModuleName].View.tsx          // Single item view components
+├── [ModuleName].Zone.tsx          // Main zone layout and routing
+├── _server.ts                     // Module registration
+├── [module-name].constant.ts      // Model definitions
+├── [module-name].dictionary.ts    // Translations
+├── [module-name].document.ts      // Database schema
+├── [module-name].service.ts       // Business logic
+├── [module-name].signal.ts        // API endpoints
+├── [module-name].store.ts         // Client state management
+└── index.tsx                      // Module exports
+```
+
+## How to Create Database Modules
+
+### 1. Define Model Schema (`[module-name].constant.ts`)
+
+Start by defining your data model schema using the decorator pattern:
+
+```typescript
+import { Dayjs, dayjs, enumOf, Int } from "@akanjs/base";
+import { Field, Filter, Model, sortOf, via } from "@akanjs/constant";
+import { validate } from "@util/common";
+
+// Define enums
+export const UserRole = enumOf(["user", "admin"] as const);
+export type UserRole = enumOf<typeof UserRole>;
+
+// Define input model (for create/update operations)
+@Model.Input("UserInput")
+export class UserInput {
+  @Field.Prop(() => String, { validate: validate.email, type: "email", example: "user@example.com" })
+  email: string;
+
+  @Field.Secret(() => String, { nullable: true, type: "password", example: "password123" })
+  password: string | null;
+}
+
+// Define object model (full data model)
+@Model.Object("UserObject")
+export class UserObject extends via(UserInput) {
+  @Field.Prop(() => [String], [{ enum: UserRole, example: ["user"] }])
+  roles: (typeof UserRole.value)[];
+
+  @Field.Prop(() => Date, { default: () => dayjs(), example: dayjs() })
+  lastLoginAt: Dayjs;
+}
+
+// Define light model (client-side model with essential fields)
+@Model.Light("LightUser")
+export class LightUser extends via(UserObject, ["email", "roles"] as const) {
+  hasAccess(role: UserRole) {
+    return this.roles.includes(role);
+  }
+}
+
+// Define full model (server-side model with all fields)
+@Model.Full("User")
+export class User extends via(UserObject, LightUser) {}
+
+// Define filter model (for queries)
+@Model.Filter("UserFilter")
+export class UserFilter extends sortOf(User, {}) {
+  @Filter.Mongo()
+  byEmail(@Filter.Arg("email", () => String) email: string) {
+    return { email };
+  }
+}
+```
+
+### 2. Implement Database Schema (`[module-name].document.ts`)
+
+Create the MongoDB schema with document methods and middleware:
+
+```typescript
+import { dayjs } from "@akanjs/base";
+import { beyond, by, Database, into, Loader, type SchemaOf } from "@akanjs/document";
+import { hashPassword } from "@shared/nest";
+
+import { cnst } from "../cnst";
+
+// Input model for database operations
+@Database.Input(() => cnst.UserInput)
+export class UserInput extends by(cnst.UserInput) {}
+
+// Document model with methods
+@Database.Document(() => cnst.User)
+export class User extends by(cnst.User) {
+  addRole(role: cnst.UserRole) {
+    if (!this.roles.includes(role)) this.roles = [...this.roles, role];
+    return this;
+  }
+
+  updateLastLogin() {
+    this.lastLoginAt = dayjs();
+    return this;
+  }
+}
+
+// Model with database operations
+@Database.Model(() => cnst.User)
+export class UserModel extends into(User, cnst.userCnst) {
+  @Loader.ByField("email") userEmailLoader: Loader<string, User>;
+
+  async findByEmail(email: string) {
+    return this.User.findOne({ email, removedAt: { $exists: false } });
+  }
+
+  async getUserSecret(email: string) {
+    return this.User.pickOne({ email, removedAt: { $exists: false } }, { roles: true, password: true });
+  }
+}
+
+// Middleware for hooks and indexes
+@Database.Middleware(() => cnst.User)
+export class UserMiddleware extends beyond(UserModel, User) {
+  onSchema(schema: SchemaOf<UserModel, User>) {
+    // Hash password before saving
+    schema.pre<User>("save", async function (next) {
+      if (!this.isModified("password") || !this.password) {
+        next();
+        return;
+      }
+      const encryptedPassword = await hashPassword(this.password);
+      this.password = encryptedPassword;
+      next();
+    });
+
+    // Create indexes
+    schema.index({ email: 1 }, { unique: true });
+    schema.index({ email: "text" });
+  }
+}
+```
+
+### 3. Create Service (`[module-name].service.ts`)
+
+Implement business logic in the service:
+
+```typescript
+import { DbService, Service, Srv, Use } from "@akanjs/service";
+import { Account, type Me } from "@akanjs/signal";
+import { isPasswordMatch } from "@shared/nest";
+
+import { cnst } from "../cnst";
+import * as db from "../db";
+import type * as option from "../option";
+import type * as srv from "../srv";
+
+@Service("UserService")
+export class UserService extends DbService(db.userDb) {
+  @Use() protected readonly config: option.SecurityConfig;
+  @Srv() protected readonly securityService: srv.util.SecurityService;
+
+  async signin(email: string, password: string, account?: Account) {
+    const userSecret = await this.userModel.getUserSecret(email);
+    if (!userSecret) throw new Error("User not found");
+
+    const matched = await isPasswordMatch(password, userSecret.password || "");
+    if (!matched) throw new Error("Invalid credentials");
+
+    const user = await this.userModel.getUser(userSecret.id);
+    await user.updateLastLogin().save();
+
+    return this.securityService.addJwt({ me: user }, account);
+  }
+
+  async addRole(userId: string, role: cnst.UserRole) {
+    const user = await this.userModel.getUser(userId);
+    return await user.addRole(role).save();
+  }
+
+  async createUser(data: db.UserInput) {
+    const existingUser = await this.userModel.findByEmail(data.email);
+    if (existingUser) throw new Error("User already exists");
+
+    const user = await this.userModel.createUser(data);
+    return await user.set({ roles: ["user"] }).save();
+  }
+}
+```
+
+### 4. Create Signal (`[module-name].signal.ts`)
+
+Define GraphQL operations in the signal:
+
+```typescript
+import { ID } from "@akanjs/base";
+import { Account, Arg, DbSignal, Me, Mutation, Query, resolve, Signal } from "@akanjs/signal";
+
+import { cnst, Srvs } from "../cnst";
+import type * as db from "../db";
+
+@Signal(() => cnst.User)
+export class UserSignal extends DbSignal(cnst.userCnst, Srvs, {
+  guards: { get: Query.Public, cru: Mutation.Admin },
+}) {
+  @Mutation.Public(() => cnst.util.AccessToken)
+  async signin(
+    @Arg.Body("email", () => String, { example: "user@example.com" }) email: string,
+    @Arg.Body("password", () => String, { example: "password123" }) password: string,
+    @Account() account: Account
+  ) {
+    const accessToken = await this.userService.signin(email, password, account);
+    return resolve<cnst.util.AccessToken>(accessToken);
+  }
+
+  @Query.User(() => cnst.User)
+  async me(@Me() me: Me) {
+    const user = await this.userService.getUser(me.id);
+    return resolve<cnst.User>(user);
+  }
+
+  @Mutation.Admin(() => cnst.User)
+  async createUser(@Arg.Body("data", () => cnst.UserInput) data: db.UserInput) {
+    const user = await this.userService.createUser(data);
+    return resolve<cnst.User>(user);
+  }
+
+  @Mutation.Admin(() => cnst.User)
+  async addUserRole(
+    @Arg.Param("userId", () => ID) userId: string,
+    @Arg.Body("role", () => String) role: cnst.UserRole
+  ) {
+    const user = await this.userService.addRole(userId, role);
+    return resolve<cnst.User>(user);
+  }
+}
+```
+
+### 5. Create Store (`[module-name].store.ts`)
+
+Implement client-side state management:
+
+```typescript
+import { StateCreator } from "zustand";
+import { immer } from "zustand/middleware/immer";
+
+import { cnst } from "../cnst";
+import * as fetch from "../fetch";
+
+export interface UserState {
+  users: cnst.User[];
+  selectedUser?: cnst.User;
+  userForm: cnst.UserInput;
+}
+
+export interface UserAction {
+  setUsers: (users: cnst.User[]) => void;
+  selectUser: (user?: cnst.User) => void;
+  setUserForm: (form: Partial<cnst.UserInput>) => void;
+  resetUserForm: () => void;
+  signin: () => Promise<void>;
+  createUser: () => Promise<void>;
+}
+
+export type UserStore = UserState & UserAction;
+
+export const createUserStore: StateCreator<UserStore, [["zustand/immer", never]], [], UserStore> = immer(
+  (set, get) => ({
+    users: [],
+    userForm: { email: "", password: null },
+
+    setUsers: (users) =>
+      set((state) => {
+        state.users = users;
+      }),
+    selectUser: (user) =>
+      set((state) => {
+        state.selectedUser = user;
+      }),
+    setUserForm: (form) =>
+      set((state) => {
+        state.userForm = { ...state.userForm, ...form };
+      }),
+    resetUserForm: () =>
+      set((state) => {
+        state.userForm = { email: "", password: null };
+      }),
+
+    signin: async () => {
+      const { email, password } = get().userForm;
+      if (!password) return;
+      await fetch.user.signin(email, password);
+      get().resetUserForm();
+    },
+
+    createUser: async () => {
+      const { userForm } = get();
+      const user = await fetch.user.createUser({ data: userForm });
+      set((state) => {
+        state.users = [...state.users, user];
+        state.userForm = { email: "", password: null };
+      });
+    },
+  })
+);
+```
+
+### 6. Create Dictionary (`[module-name].dictionary.ts`)
+
+Define internationalization strings:
+
+```typescript
+export const userDict = {
+  email: {
+    ko: "이메일",
+    en: "Email",
+  },
+  password: {
+    ko: "비밀번호",
+    en: "Password",
+  },
+  signin: {
+    ko: "로그인",
+    en: "Sign In",
+  },
+  user_list: {
+    ko: "사용자 목록",
+    en: "User List",
+  },
+  add_user: {
+    ko: "사용자 추가",
+    en: "Add User",
+  },
+};
+```
+
+### 7. Register Module (`_server.ts`)
+
+Create module registration for the server:
+
+```typescript
+import { databaseModuleOf } from "@akanjs/server";
+
+import { cnst } from "../cnst";
+import * as db from "../db";
+import type { ModulesOptions } from "../option";
+import { allSrvs } from "../srv";
+import { UserService } from "./user.service";
+import { UserSignal } from "./user.signal";
+
+export const registerUserModule = (option: ModulesOptions) =>
+  databaseModuleOf(
+    {
+      constant: cnst.userCnst,
+      database: db.userDb,
+      signal: UserSignal,
+      service: UserService,
+      uses: { securityConfig: option.securityConfig },
+    },
+    allSrvs
+  );
+```
+
+### 8. Create UI Components
+
+#### Template Component (`[ModuleName].Template.tsx`)
+
+```tsx
+import { Button, Form } from "@util/ui";
+
+import { dict } from "../dict";
+import { st } from "../st";
+
+export const General = () => {
+  const { userForm } = st.use.user();
+  const { signin, setUserForm } = st.do.user();
+
+  return (
+    <Form onSubmit={signin}>
+      <Form.Item label={dict.user.email}>
+        <Form.Input type="email" value={userForm.email} onChange={(e) => setUserForm({ email: e.target.value })} />
+      </Form.Item>
+      <Form.Item label={dict.user.password}>
+        <Form.Input
+          type="password"
+          value={userForm.password || ""}
+          onChange={(e) => setUserForm({ password: e.target.value })}
+        />
+      </Form.Item>
+      <Button type="submit">{dict.user.signin}</Button>
+    </Form>
+  );
+};
+```
+
+#### Unit Component (`[ModuleName].Unit.tsx`)
+
+```tsx
+import { Card, ModelProps } from "@util/ui";
+
+export const UserCard = ({ user }: ModelProps<"user">) => (
+  <Card>
+    <Card.Title>{user.email}</Card.Title>
+    <Card.Content>
+      <div>Roles: {user.roles.join(", ")}</div>
+    </Card.Content>
+  </Card>
+);
+```
+
+#### View Component (`[ModuleName].View.tsx`)
+
+```tsx
+import { useEffect } from "react";
+import { Container, ListContainer } from "@util/ui";
+
+import * as Unit from "./User.Unit";
+import * as Template from "./User.Template";
+import { st } from "../st";
+import { sig } from "../sig";
+
+export const List = () => {
+  const { users } = st.use.user();
+
+  useEffect(() => {
+    void sig.user.getUsers().then((data) => {
+      st.do.user().setUsers(data.users);
+    });
+  }, []);
+
+  return (
+    <Container>
+      <ListContainer items={users} renderItem={(user) => <Unit.UserCard user={user} />} emptyText="No users found" />
+    </Container>
+  );
+};
+```
+
+#### Zone Component (`[ModuleName].Zone.tsx`)
+
+```tsx
+import { Zone } from "@util/ui";
+
+import * as View from "./User.View";
+import * as Template from "./User.Template";
+import { dict } from "../dict";
+
+export const User = () => (
+  <Zone title={dict.user.user_list}>
+    <Zone.Section title={dict.user.add_user}>
+      <Template.General />
+    </Zone.Section>
+    <Zone.Section>
+      <View.List />
+    </Zone.Section>
+  </Zone>
+);
+```
+
+#### Client Exports (`index.tsx`)
+
+```tsx
+import { Signal } from "@util/ui";
+import { FaUser } from "react-icons/fa";
+
+import * as Template from "./User.Template";
+import * as Unit from "./User.Unit";
+import * as Util from "./User.Util";
+import * as View from "./User.View";
+import * as Zone from "./User.Zone";
+
+export const User = {
+  Menu: {
+    User: {
+      key: "user",
+      label: "Users",
+      icon: <FaUser />,
+      render: () => <Zone.User />,
+    },
+  },
+  Template,
+  Unit,
+  Util,
+  View,
+  Zone,
+};
+```
+
+## How to Use Database Modules in Nest.js Server
+
+### 1. Register Module in Server Bootstrap
+
+In your server bootstrap file:
+
+```typescript
+import { createNestApp } from "@akanjs/server";
+import { registerUserModule } from "./user/_server";
+import { registerAdminModule } from "./admin/_server";
+
+const startServer = async () => {
+  const app = await createNestApp({
+    env: serverEnv,
+    registerModules: (options) => [
+      registerUserModule(options),
+      registerAdminModule(options),
+      // Register other modules...
+    ],
+  });
+
+  return app;
+};
+```
+
+### 2. Using Services in Controllers or Other Services
+
+```typescript
+import { Controller, Get } from "@nestjs/common";
+import { UserService } from "./user/user.service";
+
+@Controller("auth")
+export class AuthController {
+  constructor(private readonly userService: UserService) {}
+
+  @Get("users")
+  async getUsers() {
+    return this.userService.getUsers({});
+  }
+}
+```
+
+## How to Use Components, Stores, and Signals in Client Side
+
+### 1. Using Components in Pages
+
+```tsx
+import { User } from "@shared/lib/user";
+
+export default function UserPage() {
+  return (
+    <main>
+      <User.Zone.User />
+    </main>
+  );
+}
+```
+
+### 2. Using Stores for State Management
+
+```tsx
+import { st } from "@shared/client";
+
+const UserComponent = () => {
+  const { users, selectedUser } = st.use.user();
+  const { selectUser, setUsers } = st.do.user();
+
+  // Use the store state and actions
+  return (
+    <div>
+      {users.map((user) => (
+        <div key={user.id} onClick={() => selectUser(user)} className={selectedUser?.id === user.id ? "selected" : ""}>
+          {user.email}
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+### 3. Using Signals for API Calls
+
+```tsx
+import { useEffect, useState } from "react";
+import { sig } from "@shared/client";
+
+const UserData = () => {
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setLoading(true);
+    sig.user
+      .getUsers()
+      .then((data) => {
+        st.do.user().setUsers(data.users);
+        setLoading(false);
+      })
+      .catch((err) => {
+        setError(err.message);
+        setLoading(false);
+      });
+  }, []);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return <User.View.List />;
+};
+```
+
+### 4. Integrating with Menu System
+
+```tsx
+import { AppLayout } from "@util/ui";
+import { User } from "@shared/lib/user";
+import { Admin } from "@shared/lib/admin";
+
+export const Layout = () => (
+  <AppLayout
+    pageMenus={[
+      {
+        key: "users",
+        title: "User Management",
+        menus: User.Menu,
+      },
+      {
+        key: "admin",
+        title: "Administration",
+        menus: Admin.Menu,
+      },
+    ]}
+  />
+);
+```
+
+## Best Practices
+
+1. **Naming Conventions**
+
+   - Use PascalCase for classes and components (e.g., `UserService`, `User.Unit.tsx`)
+   - Use camelCase for files (e.g., `user.service.ts`, `user.document.ts`)
+
+2. **Security**
+
+   - Use `@Field.Secret` for sensitive data like passwords
+   - Apply proper permission guards to queries and mutations (`@Query.Admin`, `@Mutation.Public`)
+   - Validate input data using the `validate` option in `@Field.Prop`
+
+3. **Code Organization**
+
+   - Keep business logic in service files
+   - Use signals for API calls only, not for business logic
+   - Define reusable utility methods in document models
+
+4. **Performance**
+
+   - Use dataloader pattern (`@Loader.ByField`) for efficient database access
+   - Create proper indexes in the middleware
+   - Use projections to limit returned fields when appropriate
+
+5. **Testing**
+
+   - Create signal tests for each API endpoint
+   - Mock services for unit testing signals
+   - Use integration tests for testing complex workflows
+
+6. **UI Components**
+
+   - Follow the separation between Template, Unit, View, and Zone components
+   - Make components reusable across different parts of the application
+   - Use dictionary files for all UI text to support internationalization
+
+7. **Real-time Features**
+   - Use GraphQL subscriptions for real-time updates
+   - Use WebSockets for bidirectional communication
+   - Use Bull queues for background processing
+
+## Data Flow in Database Modules
+
+1. **User Interaction** → User interacts with a component (e.g., submits a form)
+2. **Store Action** → Action in store is triggered (e.g., `st.do.user().signin()`)
+3. **Signal Call** → Signal method is called (e.g., `sig.user.signin()`)
+4. **GraphQL Request** → GraphQL request is sent to the server
+5. **Resolver** → NestJS resolver (generated from Signal) handles the request
+6. **Service** → Service method processes the business logic
+7. **Database** → Database operations are performed
+8. **Response** → Result is returned through the GraphQL API
+9. **Store Update** → Client state is updated based on the response
+10. **UI Update** → Components re-render with the updated state