@youjunhuang/entity-core

Shared entity core library for Mycena core.

Installation

npm i --save-dev @youjunhuang/entity-core

Concepts

This library is structured around three main concepts:

1. Models (/models)

Database-agnostic entity definitions. These are pure TypeScript interfaces and enums that define the shape of your data entities. They are independent of any specific database implementation.

• Purpose: Define the "What".
• Example: Camera, User, Event.

2. Schemas (/schemas)

Database-specific implementations. These define how the Models are mapped to a specific database (e.g., MongoDB via Mongoose, SQL via TypeORM).

• Purpose: Define the "How" (storage).
• Current Support: MongoDB (/schemas/mongo).

3. Data Access (/data_access)

Repositories and Services. These provide the logic to interact with the database using the Schemas. They abstract the database operations from the business logic.

• Purpose: Define the "How" (access).
• Current Support: MongoDB Repositories (/data_access/mongo).

Usage

Importing Models

Use Models to type your objects and ensure type safety across your application.

import { Camera, CameraStatus, CameraType } from '@youjunhuang/entity-core';

const myCamera: Camera = {
  id: 'cam-001',
  name: 'Front Door',
  type: CameraType.SHOTGUN,
  status: CameraStatus.Online,
  // ... other properties
};

Using Schemas (NestJS Example)

Import Schemas to define your Mongoose models in a NestJS application.

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { CameraMongo, CameraMongoSchema } from '@youjunhuang/entity-core';

@Module({
  imports: [
    MongooseModule.forFeature([
      { name: CameraMongo.name, schema: CameraMongoSchema },
    ]),
  ],
})
export class CameraModule {}

Using Data Access Repositories

Import and use Repositories to perform database operations.

import { Injectable } from '@nestjs/common';
import { CameraMongoRepository } from '@youjunhuang/entity-core';

@Injectable()
export class CameraService {
  constructor(private readonly cameraRepo: CameraMongoRepository) {}

  async findAll() {
    return this.cameraRepo.findAll();
  }
}

Publishing

Pack vs Release 差別

| 項目 | pack | release | |------|--------|-----------| | 作用 | 打包成 .tgz 檔案 | 發布到 npm registry | | 結果 | 產生本地 .tgz 檔案 | 套件上傳到 npmjs.com | | 用途 | 本地測試、私有分發 | 正式發布給公眾使用 | | 可逆性 | ✅ 隨時刪除 .tgz 檔 | ⚠️ 發布後 72 小時內才能 unpublish |

Pack (打包測試)

自動迭代版本號並打包為 .tgz 檔案：

pnpm run pack:patch   # 版本號 +0.0.1 (e.g. 1.0.12 → 1.0.13)
pnpm run pack:minor   # 版本號 +0.1.0 (e.g. 1.0.12 → 1.1.0)
pnpm run pack:major   # 版本號 +1.0.0 (e.g. 1.0.12 → 2.0.0)

Release (發布到 npm)

自動迭代版本號並發布到 npm：

pnpm run release:patch   # 版本號 +0.0.1，發布
pnpm run release:minor   # 版本號 +0.1.0，發布
pnpm run release:major   # 版本號 +1.0.0，發布

建議工作流程

方式一：先測試後發布（推薦）

# 1. 打包並 bump 版本
pnpm run pack:patch

# 2. 在其他專案本地安裝測試
npm install ../entity_core/typescript/youjunhuang-entity-core-x.x.x.tgz

# 3. 測試通過後，直接發布當前版本（不再 bump）
npm publish --access public

方式二：直接發布

# 確定套件沒問題，直接 bump 版本並發布
pnpm run release:patch

[!WARNING] 不要連續執行 pnpm pack:patch && pnpm release:patch！ 這會導致版本號跳兩次（pack 一次 + release 一次）。

[!NOTE] 發布前請確保已登入 npm (npm login)。