sonamu 0.5.7 → 0.7.0

package/src/api/config.ts

@@ -0,0 +1,125 @@
+import type { FastifyCorsOptions } from "@fastify/cors";
+import type { FastifyFormbodyOptions } from "@fastify/formbody";
+import type { FastifyMultipartOptions } from "@fastify/multipart";
+import type { DeserializeFunction, SerializeFunction } from "@fastify/passport/dist/Authenticator";
+import type { SecureSessionPluginOptions } from "@fastify/secure-session";
+import type { FastifyStaticOptions } from "@fastify/static";
+import type { FastifyInstance, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
+import type { QsPluginOptions } from "fastify-qs";
+import type { SsePluginOptions } from "fastify-sse-v2/lib/types";
+import type { Knex } from "knex";
+import type { Driver } from "../file-storage/driver";
+import type { SonamuFastifyConfig } from "../types/types";
+
+export type DatabaseConfig = Omit<Knex.Config, "connection"> & {
+  connection?: Knex.PgConnectionConfig;
+};
+
+export type SonamuConfig = {
+  projectName?: string;
+
+  api: {
+    dir: string;
+    route: {
+      prefix: string;
+    };
+    timezone?: string;
+  };
+  sync: {
+    targets: string[]; // "web", "app" 등
+  };
+  ui?: {
+    port: number;
+  };
+
+  database: {
+    // 데이터베이스
+    database?: "postgresql";
+    // 기본 데이터베이스 이름
+    name: string;
+    // 모든 환경에 적용될 기본 Knex 옵션
+    defaultOptions: DatabaseConfig;
+    // 환경별 설정
+    environments?: {
+      development?: DatabaseConfig;
+      development_slave?: DatabaseConfig;
+      production?: DatabaseConfig;
+      production_slave?: DatabaseConfig;
+      remote_fixture?: DatabaseConfig;
+    };
+  };
+
+  server: SonamuServerOptions;
+};
+
+export type SonamuServerOptions = {
+  fastify?: FastifyServerOptions;
+
+  listen?: {
+    port: number;
+    host?: string;
+  };
+
+  plugins?: {
+    cors?: boolean | FastifyCorsOptions;
+    formbody?: boolean | FastifyFormbodyOptions;
+    multipart?: boolean | FastifyMultipartOptions;
+    qs?: boolean | QsPluginOptions;
+    sse?: boolean | SsePluginOptions;
+    static?: boolean | FastifyStaticOptions;
+    session?: boolean | SecureSessionPluginOptions;
+
+    custom?: (server: FastifyInstance) => void;
+  };
+
+  auth?:
+    | boolean
+    | {
+        userSerializer: SerializeFunction<unknown, unknown>;
+        userDeserializer: DeserializeFunction<unknown, unknown>;
+      };
+
+  apiConfig: SonamuFastifyConfig;
+
+  storage?: Driver;
+
+  lifecycle?: {
+    onStart?: (server: FastifyInstance) => Promise<void> | void;
+    onShutdown?: (server: FastifyInstance) => Promise<void> | void;
+    onError?: (error: Error, request: FastifyRequest, reply: FastifyReply) => Promise<void> | void;
+  };
+};
+
+export type SonamuConfigExport = SonamuConfig | Promise<SonamuConfig>;
+
+export function defineConfig(config: SonamuConfig): SonamuConfig;
+export function defineConfig(config: Promise<SonamuConfig>): Promise<SonamuConfig>;
+export function defineConfig(config: SonamuConfigExport): SonamuConfigExport {
+  return config;
+}
+
+/**
+ * sonamu.config.ts 파일을 로드합니다.
+ * 이 설정 파일은 환경에 따라 다른 경로에 있을 수 있습니다.
+ * dist를 빌드하는 환경이라면 dist 바로 아래에 있을 것이고(cli-wrapper.ts에서 빌드),
+ * 그렇지 않은 환경이라면 프로젝트 루트에 있을 것입니다.
+ *
+ * 이 함수는 의도적으로 다른 의존성의 사용을 최대한 배제하였습니다.
+ * 이는 실행 초기에 최대한 빠르게 설정을 읽어올 수 있도록 하기 위함입니다.
+ * 따라서 경로 concat과 URL scheme 추가도 단순한 문자열 조작으로 처리하였습니다.
+ *
+ * @param rootPath
+ * @returns
+ */
+export async function loadConfig(rootPath: string): Promise<SonamuConfig> {
+  const start = performance.now();
+  const configPath =
+    process.env.HOT === "yes" || process.env.VITEST === "true"
+      ? `${rootPath}/sonamu.config.ts`
+      : `${rootPath}/dist/sonamu.config.js`;
+  const { default: config } = await import(`file://${configPath}`);
+  const importTime = performance.now() - start;
+  process.env.NODE_ENV !== "test" &&
+    console.log(`[TIMING] loadConfig took ${importTime.toFixed(2)}ms`);
+  return config;
+}

package/src/api/context.ts

@@ -1,29 +1,19 @@
 import type { FastifyReply, FastifyRequest, PassportUser } from "fastify";
 import type { RouteGenericInterface } from "fastify/types/route";
-import type {
-  Server,
-  IncomingMessage,
-  ServerResponse,
-  IncomingHttpHeaders,
-} from "http";
-import type { FileStorage } from "../file-storage/file-storage";
+import type { IncomingHttpHeaders, IncomingMessage, Server, ServerResponse } from "http";
 import type { ZodObject } from "zod";
+import type { FileStorage } from "../file-storage/file-storage";
+import type { NaiteStore } from "../naite/naite";
 import type { createSSEFactory } from "../stream/sse";
 
+// biome-ignore lint/suspicious/noEmptyInterface: Context 확장 타입
 export interface ContextExtend {}
 export type Context = {
   request: FastifyRequest;
-  reply: FastifyReply<
-    Server,
-    IncomingMessage,
-    ServerResponse,
-    RouteGenericInterface,
-    unknown
-  >;
+  reply: FastifyReply<Server, IncomingMessage, ServerResponse, RouteGenericInterface, unknown>;
   headers: IncomingHttpHeaders;
-  createSSE: <T extends ZodObject>(
-    events: T
-  ) => ReturnType<typeof createSSEFactory<T>>;
+  createSSE: <T extends ZodObject>(events: T) => ReturnType<typeof createSSEFactory<T>>;
+  naiteStore: NaiteStore;
 } & AuthContext &
   ContextExtend;
 

package/src/api/decorators.ts

@@ -1,15 +1,18 @@
+import assert from "assert";
 import type { HTTPMethods } from "fastify";
 import inflection from "inflection";
-import type { ApiParam, ApiParamType } from "../types/types";
-import { z } from "zod";
+import { isEqual } from "radashi";
+import type { z } from "zod";
+import type { BaseModelClass } from "../database/base-model";
+import { DB } from "../database/db";
 import {
   PuriTransactionWrapper,
-  PuriWrapper,
-  TransactionalOptions,
+  type PuriWrapper,
+  type TransactionalOptions,
 } from "../database/puri-wrapper";
-import { DB } from "../database/db";
-import { Sonamu } from "./sonamu";
+import type { ApiParam, ApiParamType } from "../types/types";
 import type { UploadContext } from "./context";
+import { Sonamu } from "./sonamu";
 
 export interface GuardKeys {
   query: true;
@@ -17,11 +20,7 @@ export interface GuardKeys {
   user: true;
 }
 export type GuardKey = keyof GuardKeys;
-export type ServiceClient =
-  | "axios"
-  | "axios-multipart"
-  | "swr"
-  | "window-fetch";
+export type ServiceClient = "axios" | "axios-multipart" | "swr" | "window-fetch";
 export type ApiDecoratorOptions = {
   httpMethod?: HTTPMethods;
   contentType?:
@@ -39,6 +38,7 @@ export type ApiDecoratorOptions = {
 };
 export type StreamDecoratorOptions = {
   type: "sse"; // | 'ws
+  // biome-ignore lint/suspicious/noExplicitAny: 이벤트 키별로 넘겨주는 값이므로 어떤 타입이든 상관없음
   events: z.ZodObject<any>;
   path?: string;
   resourceName?: string;
@@ -49,6 +49,9 @@ export type UploadDecoratorOptions = {
   mode?: "single" | "multiple";
 };
 export const registeredApis: {
+  /**
+   * modelName은 모델 클래스 이름입니다. (ex. "UserModel")
+   */
   modelName: string;
   methodName: string;
   path: string;
@@ -67,6 +70,23 @@ export type ExtendedApi = {
   parameters: ApiParam[];
   returnType: ApiParamType;
 };
+type DecoratorTarget = { constructor: { name: string } };
+
+const DECORATOR_TYPES = {
+  API: Symbol("api"),
+  STREAM: Symbol("stream"),
+} as const;
+
+function checkSingleDecorator(target: DecoratorTarget, propertyKey: string, decoratorType: symbol) {
+  const method = target[propertyKey as keyof typeof target] as { __decoratorType?: symbol };
+  if (method?.__decoratorType && method?.__decoratorType !== decoratorType) {
+    throw new Error(
+      `@${String(decoratorType)} decorator can only be used once on ${target.constructor.name}.${propertyKey}. You can use only one of @api or @stream decorator on the same method.`,
+    );
+  } else {
+    method.__decoratorType = decoratorType;
+  }
+}
 
 export function api(options: ApiDecoratorOptions = {}) {
   options = {
@@ -76,26 +96,43 @@ export function api(options: ApiDecoratorOptions = {}) {
     ...options,
   };
 
-  return function (target: Object, propertyKey: string) {
-    const modelName = target.constructor.name.match(/(.+)Class$/)![1];
+  return (target: DecoratorTarget, propertyKey: string) => {
+    const modelName = target.constructor.name.match(/(.+)Class$/)?.[1];
+    assert(
+      modelName,
+      `modelName is required on @api decorator on ${target.constructor.name}.${propertyKey}`,
+    );
     const methodName = propertyKey;
 
+    // 메서드에 걸린 데코레이터 중복 체크
+    checkSingleDecorator(target, propertyKey, DECORATOR_TYPES.API);
+
     const defaultPath = `/${inflection.camelize(
       modelName.replace(/Model$/, "").replace(/Frame$/, ""),
-      true
+      true,
     )}/${inflection.camelize(propertyKey, true)}`;
+    const path = options.path ?? defaultPath;
 
     // 기존 동일한 메서드가 있는지 확인 후 있는 경우 override
     const existingApi = registeredApis.find(
-      (api) => api.modelName === modelName && api.methodName === methodName
+      (api) => api.modelName === modelName && api.methodName === methodName,
     );
     if (existingApi) {
-      existingApi.options = options;
+      // 기존의 path와 새로운 path가 다르다면(=빈 스트링이 아니었는데 다른 스트링으로 바뀌게 된다면) 에러를 터뜨려줍니다.
+      assertNoConflictingPath("api", modelName, methodName, existingApi.path, path);
+      existingApi.path = path;
+
+      // 기존의 옵션과 새로운 옵션이 겹치는 부분이 있다면 에러를 터뜨려줍니다.
+      assertNoConflictingOptions("api", modelName, methodName, existingApi.options, options);
+      existingApi.options = {
+        ...existingApi.options, // 기존의 옵션을 존중하되
+        ...options, // @api 데코레이터의 옵션을 추가합니다.
+      };
     } else {
       registeredApis.push({
         modelName,
         methodName,
-        path: options.path ?? defaultPath,
+        path,
         options,
       });
     }
@@ -103,29 +140,55 @@ export function api(options: ApiDecoratorOptions = {}) {
 }
 
 export function stream(options: StreamDecoratorOptions) {
-  return function (target: Object, propertyKey: string) {
-    const modelName = target.constructor.name.match(/(.+)Class$/)![1];
+  return (target: DecoratorTarget, propertyKey: string) => {
+    const modelName = target.constructor.name.match(/(.+)Class$/)?.[1];
+    assert(
+      modelName,
+      `modelName is required on @stream decorator on ${target.constructor.name}.${propertyKey}`,
+    );
     const methodName = propertyKey;
 
+    // 메서드에 걸린 데코레이터 중복 체크
+    checkSingleDecorator(target, propertyKey, DECORATOR_TYPES.STREAM);
+
     const defaultPath = `/${inflection.camelize(
       modelName.replace(/Model$/, "").replace(/Frame$/, ""),
-      true
+      true,
     )}/${inflection.camelize(propertyKey, true)}`;
+    const path = options.path ?? defaultPath;
+    const optionsWithDefaults = {
+      ...options,
+      httpMethod: "GET" as HTTPMethods,
+    };
 
     const existingApi = registeredApis.find(
-      (api) => api.modelName === modelName && api.methodName === methodName
+      (api) => api.modelName === modelName && api.methodName === methodName,
     );
     if (existingApi) {
-      existingApi.options = options;
+      // 기존의 path와 새로운 path가 다르다면(=빈 스트링이 아니었는데 다른 스트링으로 바뀌게 된다면) 에러를 터뜨려줍니다.
+      assertNoConflictingPath("stream", modelName, methodName, existingApi.path, path);
+      existingApi.path = path;
+
+      // 기존의 옵션과 새로운 옵션이 겹치는 부분이 있다면 에러를 터뜨려줍니다.
+      assertNoConflictingOptions(
+        "stream",
+        modelName,
+        methodName,
+        existingApi.options,
+        optionsWithDefaults,
+      );
+      existingApi.options = {
+        ...existingApi.options, // 기존의 옵션을 존중하되
+        ...optionsWithDefaults, // @stream 데코레이터의 옵션을 추가합니다.
+      };
+
+      existingApi.streamOptions = options;
     } else {
       registeredApis.push({
         modelName,
         methodName,
-        path: options.path ?? defaultPath,
-        options: {
-          ...options,
-          httpMethod: "GET",
-        },
+        path,
+        options: optionsWithDefaults,
         streamOptions: options,
       });
     }
@@ -135,14 +198,10 @@ export function stream(options: StreamDecoratorOptions) {
 export function transactional(options: TransactionalOptions = {}) {
   const { isolation, readOnly, dbPreset = "w" } = options;
 
-  return function (
-    _target: Object,
-    _propertyKey: string,
-    descriptor: PropertyDescriptor
-  ) {
+  return (_target: DecoratorTarget, _propertyKey: string, descriptor: PropertyDescriptor) => {
     const originalMethod = descriptor.value;
 
-    descriptor.value = async function (this: any, ...args: any[]) {
+    descriptor.value = async function (this: BaseModelClass, ...args: unknown[]) {
       const existingContext = DB.transactionStorage.getStore();
 
       // 이미 AsyncLocalStorage 컨텍스트 안에 있는지 확인
@@ -159,10 +218,7 @@ export function transactional(options: TransactionalOptions = {}) {
 
         return puri.knex.transaction(
           async (trx) => {
-            const trxWrapper = new PuriTransactionWrapper(
-              trx,
-              this.getUpsertBuilder()
-            );
+            const trxWrapper = new PuriTransactionWrapper(trx, this.getUpsertBuilder());
             // TransactionContext에 트랜잭션 저장
             DB.getTransactionContext().setTransaction(dbPreset, trxWrapper);
 
@@ -173,7 +229,7 @@ export function transactional(options: TransactionalOptions = {}) {
               DB.getTransactionContext().deleteTransaction(dbPreset);
             }
           },
-          { isolationLevel: isolation, readOnly }
+          { isolationLevel: isolation, readOnly },
         );
       };
 
@@ -190,25 +246,42 @@ export function transactional(options: TransactionalOptions = {}) {
   };
 }
 
+/**
+ * api 데코레이터와 함께 사용할 수 있습니다.
+ * @param options
+ * @returns
+ */
 export function upload(options: UploadDecoratorOptions = {}) {
-  return function (
-    _target: Object,
-    _propertyKey: string,
-    descriptor: PropertyDescriptor
-  ) {
+  return (_target: DecoratorTarget, _propertyKey: string, descriptor: PropertyDescriptor) => {
     const originalMethod = descriptor.value;
-    const modelName = _target.constructor.name.match(/(.+)Class$/)![1];
+    const modelName = _target.constructor.name.match(/(.+)Class$/)?.[1];
+    assert(
+      modelName,
+      `modelName is required on @upload decorator on ${_target.constructor.name}.${_propertyKey}`,
+    );
     const methodName = _propertyKey;
 
     // registeredApis에서 해당 API 찾아서 uploadOptions 추가
     const existingApi = registeredApis.find(
-      (api) => api.modelName === modelName && api.methodName === methodName
+      (api) => api.modelName === modelName && api.methodName === methodName,
     );
     if (existingApi) {
       existingApi.uploadOptions = options;
+    } else {
+      // 이 메소드에 붙은 @api 데코레이터가 아직 eval되지 않은 상황입니다. (만약 @api가 안 붙어 있었다면 심각한 상황입니다..!)
+      // 여기에서 최초로 modelName과 methodName에 대해 registeredApis에 하나를 추가해주어야 합니다.
+      // uploadOptions는 그대로 추가하고, path는 빈 스트링으로 추가해줍니다.
+      // 이후 @api 데코레이터가 eval되면 실제 path로 덮어씌워지고, options가 추가됩니다.
+      registeredApis.push({
+        modelName,
+        methodName,
+        path: "",
+        options: {},
+        uploadOptions: options,
+      });
     }
 
-    descriptor.value = async function (this: any, ...args: any[]) {
+    descriptor.value = async function (this: BaseModelClass, ...args: unknown[]) {
       const { request } = Sonamu.getContext();
       const uploadContext: UploadContext = {
         file: undefined,
@@ -225,6 +298,7 @@ export function upload(options: UploadDecoratorOptions = {}) {
         const rawFilesIterator = request.files();
         for await (const rawFile of rawFilesIterator) {
           if (rawFile) {
+            await rawFile.toBuffer();
             uploadContext.files.push(new FileStorage(rawFile, storage));
           }
         }
@@ -243,3 +317,59 @@ export function upload(options: UploadDecoratorOptions = {}) {
     return descriptor;
   };
 }
+
+/**
+ * 기존의 path와 새로운 path가 다르다면(=값이 있던 스트링이 다른 값이 있는 스트링으로 바뀌게 된다면) 에러를 터뜨려줍니다.
+ * @param decoratorName 데코레이터 이름
+ * @param modelName 모델 이름
+ * @param methodName 메서드 이름
+ * @param existingPath 기존의 path
+ * @param newPath 새로운 path
+ */
+function assertNoConflictingPath(
+  decoratorName: string,
+  modelName: string,
+  methodName: string,
+  existingPath: string,
+  newPath: string,
+) {
+  if (existingPath !== "" && newPath !== "" && existingPath !== newPath) {
+    // 이것이 무슨 상황이냐면요, api.path가 덮어씌워지는 상황입니다.
+    // 가령 @api({ path: "/api/v1/users" }) 데코레이터가 붙어있는 메서드에
+    // @stream({ path: "/api/v1/users/stream" }) 같은 것이 붙어 있는 상황입니다.
+    // 이렇게 되면 두 데코레이터가 같은 api의 path 필드를 건드리게 되므로, 에러를 터뜨려줍니다.
+    throw new Error(
+      `@${decoratorName} decorator on ${modelName}.${methodName} has conflicting path: ${newPath}. The decorator is trying to override the existing path(${existingPath}) with the new path(${newPath}).`,
+    );
+  }
+}
+
+/**
+ * 기존의 옵션과 새로운 옵션이 겹치는 부분이 있다면 에러를 터뜨려줍니다.
+ * @param decoratorName 데코레이터 이름
+ * @param modelName 모델 이름
+ * @param methodName 메서드 이름
+ * @param existingOptions 기존의 옵션
+ * @param newOptions 새로운 옵션
+ */
+function assertNoConflictingOptions(
+  decoratorName: string,
+  modelName: string,
+  methodName: string,
+  // biome-ignore lint/suspicious/noExplicitAny: <아 쉽게쉽게 좀 갑시다>
+  existingOptions: Record<string, any>,
+  // biome-ignore lint/suspicious/noExplicitAny: <이럴 때 아니면 any 언제 씁니까>
+  newOptions: Record<string, any>,
+) {
+  Object.keys(newOptions).forEach((key) => {
+    if (existingOptions[key] && !isEqual(existingOptions[key], newOptions[key])) {
+      // 이것이 무슨 상황이냐면요, api.options가 덮어씌워지는 상황입니다.
+      // 가령 @api({ resourceName: "Users" }) 데코레이터가 붙어있는 메서드에
+      // @stream({ resourceName: "Posts" }) 같은 것이 붙어 있는 상황입니다.
+      // 이렇게 되면 두 데코레이터가 같은 api의 options 속 같은 필드를 건드리게 되므로, 에러를 터뜨려줍니다.
+      throw new Error(
+        `@${decoratorName} decorator on ${modelName}.${methodName} has conflicting options: ${key}. The decorator is trying to override the existing option(${JSON.stringify(existingOptions[key])}) with the new option(${JSON.stringify(newOptions[key])}).`,
+      );
+    }
+  });
+}

package/src/api/index.ts

@@ -1,7 +1,7 @@
+export * from "../file-storage/driver";
+export * from "../file-storage/file-storage";
 export * from "./caster";
 export * from "./code-converters";
 export * from "./context";
 export * from "./decorators";
-export * from "../file-storage/driver";
-export * from "../file-storage/file-storage";
 export * from "./sonamu";