@digiforce-nc/actions

Package	@digiforce-nc/actions
Import	import { registerActions } from '@digiforce-nc/actions'

Tổng quan

@digiforce-nc/actions cung cấp bộ action handler mặc định cho các thao tác CRUD tiêu chuẩn. Khi Application khởi tạo, package này đăng ký tất cả action vào ResourceManager, cho phép mọi resource tự động có sẵn các thao tác list, get, create, update, destroy và nhiều action khác.

Mỗi action handler nhận context chứa ctx.db (Database), ctx.cache (Cache) và ctx.action (action metadata + params), rồi thực hiện thao tác tương ứng trên repository.

Không cần viết CRUD handler

Nhờ package này, khi bạn tạo một Collection mới, hệ thống tự động cung cấp đầy đủ REST API mà không cần viết code handler. Chỉ cần define collection → có ngay GET /api/posts:list, POST /api/posts:create, v.v.

---

Kiến trúc

registerActions(resourceManager)

Hàm khởi tạo, đăng ký tất cả built-in action handler vào ResourceManager:

import { registerActions } from '@digiforce-nc/actions';

// Thường được gọi trong Application constructor
registerActions(app.resourceManager);

---

Danh sách action đầy đủ

Action	HTTP Method	Mô tả	Params chính
list	GET	Danh sách phân trang	filter, sort, fields, appends, except, page, pageSize
get	GET	Lấy một record	filterByTk, fields, appends, except, filter
create	POST	Tạo record mới	values, whitelist, blacklist
update	PUT	Cập nhật record	filterByTk, values, whitelist, blacklist, filter
destroy	DELETE	Xoá record	filterByTk, filter
add	POST	Thêm association	values
remove	POST	Gỡ association	values
set	POST	Đặt association (thay thế)	values
toggle	POST	Toggle association	values
move	POST	Sắp xếp lại thứ tự	sourceId, targetId, sortField, method
query	GET	Truy vấn tổng hợp	measures, dimensions, filter, orders
firstOrCreate	POST	Tìm hoặc tạo mới	filterKeys, values
updateOrCreate	POST	Upsert	filterKeys, values

---

Chi tiết từng action

list - danh sách phân trang

GET /api/<resource>:list
GET /api/<resource>

Param	Type	Mô tả
filter	object	Điều kiện lọc. Hỗ trợ operator: $eq, $ne, $gt, $lt, $in, $like, $and, $or, ...
sort	string[]	Sắp xếp. Ví dụ: ['createdAt'] (ASC), ['-createdAt'] (DESC).
fields	string[]	Chỉ trả về các field được chỉ định.
appends	string[]	Eager load association. Ví dụ: ['author', 'tags'].
except	string[]	Loại trừ field.
page	number	Trang hiện tại (mặc định: 1).
pageSize	number	Số record mỗi trang (mặc định: 20).

Response trả về:

{
  "data": [ { "id": 1, "title": "..." }, ... ],
  "meta": { "count": 100, "page": 1, "pageSize": 20, "totalPage": 5 }
}

get - lấy một record

GET /api/<resource>:get?filterByTk=1
GET /api/<resource>/1

Param	Type	Mô tả
filterByTk	string | number	Giá trị target key (thường là id).
fields	string[]	Chỉ trả về các field được chỉ định.
appends	string[]	Eager load association.
filter	object	Điều kiện bổ sung (kết hợp AND với filterByTk).

create - tạo record mới

POST /api/<resource>:create

Param	Type	Mô tả
values	object	Dữ liệu tạo mới.
whitelist	string[]	Chỉ cho phép các field trong whitelist được ghi.
blacklist	string[]	Cấm các field trong blacklist không được ghi.

whitelist vs blacklist

whitelist và blacklist không thể dùng đồng thời. Nếu cả hai đều có, whitelist được ưu tiên.

update - cập nhật record

PUT /api/<resource>:update?filterByTk=1
PUT /api/<resource>/1

Param	Type	Mô tả
filterByTk	string | number	Target key của record cần cập nhật.
values	object	Dữ liệu cập nhật (partial update).
whitelist	string[]	Whitelist field được phép cập nhật.
blacklist	string[]	Blacklist field cấm cập nhật.
filter	object	Điều kiện bổ sung - dùng cho batch update hoặc ACL filter.

destroy - xoá record

DELETE /api/<resource>:destroy?filterByTk=1
DELETE /api/<resource>/1

Param	Type	Mô tả
filterByTk	string | number	Target key. Có thể là array để xoá nhiều (filterByTk=[1,2,3]).
filter	object	Điều kiện lọc - xoá tất cả record match filter.

Batch destroy

Khi truyền filter mà không có filterByTk, action sẽ xoá tất cả record match điều kiện. Luôn kiểm tra filter trước khi gọi.

add / remove / set / toggle - thao tác association

Dùng cho nested resource, ví dụ:

POST /api/posts/1/tags:add       - thêm tag vào post
POST /api/posts/1/tags:remove    - gỡ tag khỏi post
POST /api/posts/1/tags:set       - đặt lại toàn bộ tag
POST /api/posts/1/tags:toggle    - toggle (thêm nếu chưa có, gỡ nếu đã có)

Param	Type	Mô tả
values	number | number[]	ID (hoặc array ID) của record association.

move - sắp xếp lại thứ tự

POST /api/<resource>:move

Param	Type	Mô tả
sourceId	number	ID record cần di chuyển.
targetId	number	ID record đích (đặt trước/sau).
sortField	string	Tên field dùng để sort (mặc định: sort).
method	'insertAfter' | 'insertBefore' | 'prepend'	Phương thức di chuyển.

query - truy vấn tổng hợp

GET /api/<resource>:query

Param	Type	Mô tả
measures	Array<{ field, aggregation }>	Phép tính tổng hợp: count, sum, avg, min, max.
dimensions	Array<{ field, format? }>	Field group by.
filter	object	Điều kiện lọc.
orders	Array<{ field, order }>	Sắp xếp kết quả.

firstOrCreate - tìm hoặc tạo mới

POST /api/<resource>:firstOrCreate

Param	Type	Mô tả
filterKeys	string[]	Các field dùng để tìm record tồn tại (ví dụ: ['email']).
values	object	Dữ liệu tạo mới nếu không tìm thấy.

updateOrCreate - upsert

POST /api/<resource>:updateOrCreate

Param	Type	Mô tả
filterKeys	string[]	Các field dùng để tìm record.
values	object	Dữ liệu tạo mới hoặc cập nhật.

---

Context type

Mỗi action handler nhận Koa Context đã được augment thêm các property:

interface ActionContext extends Context {
  db: Database;               // Database instance
  cache: Cache;               // Cache instance
  action: {
    actionName: string;       // Tên action (list, get, create, ...)
    resourceName: string;     // Tên resource (posts, users, ...)
    resourceOf: string;       // Parent resource (cho nested resource)
    params: ActionParams;     // Params đã merge
  };
}

Action params và mergeParams

Params trong action context được tổng hợp từ nhiều nguồn:

Chiến lược merge cho từng loại param:

Param	Chiến lược merge
filter	Deep merge với $and - tất cả filter đều được áp dụng
fields	Intersection - chỉ giữ field có trong tất cả nguồn
appends	Union - gộp tất cả
except	Union - gộp tất cả
sort	Ghi đè - nguồn sau ghi đè nguồn trước
page, pageSize	Ghi đè
whitelist	Intersection
blacklist	Union
values	Deep merge

---

Ví dụ sử dụng

Đăng ký custom action

app.resourceManager.registerAction('posts:publish', async (ctx, next) => {
  const { filterByTk } = ctx.action.params;
  const repo = ctx.db.getRepository('posts');

  await repo.update({
    filterByTk,
    values: {
      status: 'published',
      publishedAt: new Date(),
    },
  });

  ctx.body = { success: true };
  await next();
});

Override built-in action

app.resourceManager.registerAction('posts:create', async (ctx, next) => {
  // Tự động gán author
  ctx.action.params.values = {
    ...ctx.action.params.values,
    authorId: ctx.state.currentUser.id,
  };

  // Gọi action mặc định
  const defaultCreate = require('@digiforce-nc/actions').create;
  await defaultCreate(ctx, next);
});

Sử dụng action với filter

// Client request: lấy danh sách posts đã publish, sắp xếp theo ngày tạo
const response = await api.resource('posts').list({
  filter: {
    status: 'published',
    createdAt: { $gt: '2024-01-01' },
  },
  sort: ['-createdAt'],
  fields: ['id', 'title', 'summary', 'createdAt'],
  appends: ['author'],
  page: 1,
  pageSize: 10,
});

---

Phụ thuộc

Package	Vai trò
@digiforce-nc/cache	Caching layer cho action handler (query cache)
@digiforce-nc/database	Repository/Model để thao tác dữ liệu
@digiforce-nc/resourcer	ResourceManager để đăng ký action handler

---

Đọc thêm

• Resourcer & Actions - chi tiết ResourceManager, action context, middleware pipeline.
• Database, Collection, Repository - Repository API mà action handler sử dụng.
• Data & Request flow - luồng request từ client đến action handler.
• Mã nguồn