ラベル

CoddyのNode.jsジャーニー「REST API」セクションの一部。レッスン 24/25。

タスクにはofficeやmoneyのようなラベルが付けられ、ボードアプリでは、各ラベルとそのラベルが付いたタスクの数を一覧にしたメニューが必要です。このステップでは、リストのスキーマルール、フィルター、ラベルを数えるルートの3つを追加します。以下のようにオブジェクトに数を集計するのは初めてです。

// スキーマ内の genres: z.array(z.string()).max(3).optional()
const counts = {};
for (const book of books) {
    for (const genre of book.genres) {
        counts[genre] = (counts[genre] ?? 0) + 1;
    }
}
// { poetry: 2, drama: 1 }

Object.entries(counts)を使うと、このオブジェクトを[["poetry", 2], ...]というペアに変換でき、リストにマッピングする準備が整います。このような集計結果も独立したリソースであり、専用のURLを持ちます。

optional()を使うと、このフィールドがなくてもよくなり、存在する場合には引き続き値がチェックされます。Object.entries(counts).map(([genre, count]) => ({ genre, count }))でエントリのペアをオブジェクトに変換します。角括弧で各ペアを展開し、丸括弧でオブジェクトを返します。

チャレンジ

簡単

ボードアプリでは、office や money のようなラベルでタスクを分類し、そのラベルが付いたタスクの数とともに、すべてのラベルをメニューに表示します。APIにラベル機能を追加しましょう。

routes/tasks.js で、Task スキーマに省略可能な labels フィールドを追加します。ラベルは最大5個のリストで、それぞれ前後の空白を除いた文字数が1〜20文字の文字列とします。スキーマは Task を基に作られているため、POSTとPATCHでもこのフィールドが使えるようになります。不正なリストには、通常どおり400の invalid_body エラーを返します。不正なリストには、"labels": "office"（リストではなく文字列）、"labels": [""]、ラベルが6個のリストなどがあります。
保存されるすべてのタスクに labels リストを持たせます。
- POSTまたはPUTで labels が送られなかった場合は、[] を保存します。PUTはタスク全体を置き換えるため、ラベルを指定せずにPUTするとラベルがクリアされます。
- PATCHでは、labels が送られた場合にのみ変更します。
store.js で、初期タスクにラベルを設定します。タスク1と2には ["office"]、タスク3には ["money"] を設定します。
引き続き routes/tasks.js で、一覧ルートにフィルターを追加します。GET /api/v1/tasks?label=office は、labels に office が完全に一致する形で含まれているタスクだけを返します。以前と同様に、ほかのフィルターやページ指定と組み合わせて使えます。
server.js で、ルーターのマウント箇所の隣に GET /api/v1/labels を追加し、そこで store.js から tasks をインポートします。このルートは、使用中のすべてのラベルと、そのラベルが付いたタスクの数を、ラベルのアルファベット順に返します。初期タスクの場合は次のようになります。
```
[
  { "label": "money", "count": 1 },
  { "label": "office", "count": 2 }
]
```

試してみましょう：

GET /api/v1/labels は上記のリストを返します。
/api/v1/tasks に { "title": "Order chairs", "labels": ["office"] } をPOSTします。201が返り、新しいタスクには "labels": ["office"] が設定されます。その後の GET /api/v1/labels では、office の "count": 3 が表示されます。
{ "title": "Water the plants" } をPOSTします。新しいタスクには "labels": [] が設定されます。
GET /api/v1/tasks?label=money はタスク3だけを返します。GET /api/v1/tasks?label=nope は "items": [] と "total": 0 を返します。
PUT /api/v1/tasks/2 に { "title": "Book the meeting room", "done": false } を送ると、"labels": [] が設定されたタスク2が返ります。

自分で試してみよう

import { Router } from 'express';
import { z } from 'zod';
import { config } from '../config.js';
import { sendError, sendInvalid } from '../errors.js';
import { nextId, tasks } from '../store.js';

const router = Router();

// PUT が送信する完全なタスク。.strict() は定義されていないフィールドを受け付けません。
const Task = z
    .object({
        title: z.string().trim().min(1).max(100),
        done: z.boolean(),
    })
    .strict();
const NewTask = Task.partial({ done: true });
const TaskChanges = Task.partial();
const SORT_FIELDS = ['title', 'createdAt'];

// 大文字・小文字を区別せず、別のタスクがすでにこのタイトルを持っている場合は True。
const titleTaken = (title, exceptId) =>
    tasks.some((t) => t.id !== exceptId && t.title.toLowerCase() === title.toLowerCase());

router.get('/', (req, res) => {
    const { done, q, sort } = req.query;
    let list = tasks;
    if (done !== undefined) {
        if (done !== 'true' && done !== 'false') {
            return sendError(res, 400, 'invalid_query', 'done must be true or false');
        }
        list = list.filter((t) => t.done === (done === 'true'));
    }
    if (q !== undefined) {
        const words = String(q).toLowerCase();
        list = list.filter((t) => t.title.toLowerCase().includes(words));
    }
    if (sort !== undefined) {
        const field = String(sort).startsWith('-') ? String(sort).slice(1) : String(sort);
        if (!SORT_FIELDS.includes(field)) {
            return sendError(
                res,
                400,
                'invalid_query',
                'sort must be title or createdAt, with - in front to reverse',
            );
        }
        const direction = String(sort).startsWith('-') ? -1 : 1;
        list = list.toSorted((a, b) => a[field].localeCompare(b[field]) * direction);
    }
    const page = req.query.page === undefined ? 1 : Number(req.query.page);
    const limit = req.query.limit === undefined ? config.pageSize : Number(req.query.limit);
    if (!Number.isInteger(page) || page < 1) {
        return sendError(res, 400, 'invalid_query', 'page must be a whole number from 1');
    }
    if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
        return sendError(res, 400, 'invalid_query', 'limit must be a whole number from 1 to 50');
    }
    const start = (page - 1) * limit;
    res.json({
        items: list.slice(start, start + limit),
        page,
        total: list.length,
        pages: Math.ceil(list.length / limit),
    });
});

router.get('/:id', (req, res) => {
    const task = tasks.find((t) => t.id === Number(req.params.id));
    if (!task) {
        return sendError(res, 404, 'not_found', 'Task not found');
    }
    res.json(task);
});

router.post('/', (req, res) => {
    const result = NewTask.safeParse(req.body);
    if (!result.success) {
        return sendInvalid(res, result.error);
    }
    const { title, done = false } = result.data;
    if (titleTaken(title)) {
        return sendError(res, 409, 'conflict', 'A task with this title already exists');
    }
    const task = { id: nextId(), title, done, createdAt: new Date().toISOString() };
    tasks.push(task);
    res.status(201).location(`/api/v1/tasks/${task.id}`).json(task);
});

router.patch('/:id', (req, res) => {
    const task = tasks.find((t) => t.id === Number(req.params.id));
    if (!task) {
        return sendError(res, 404, 'not_found', 'Task not found');
    }
    const result = TaskChanges.safeParse(req.body);
    if (!result.success) {
        return sendInvalid(res, result.error);
    }
    if (result.data.title !== undefined && titleTaken(result.data.title, task.id)) {
        return sendError(res, 409, 'conflict', 'A task with this title already exists');
    }
    Object.assign(task, result.data);
    res.json(task);
});

router.put('/:id', (req, res) => {
    const index = tasks.findIndex((t) => t.id === Number(req.params.id));
    if (index === -1) {
        return sendError(res, 404, 'not_found', 'Task not found');
    }
    const result = Task.safeParse(req.body);
    if (!result.success) {
        return sendInvalid(res, result.error);
    }
    const { id, createdAt } = tasks[index];
    if (titleTaken(result.data.title, id)) {
        return sendError(res, 409, 'conflict', 'A task with this title already exists');
    }
    tasks[index] = { id, ...result.data, createdAt };
    res.json(tasks[index]);
});

router.delete('/:id', (req, res) => {
    const index = tasks.findIndex((t) => t.id === Number(req.params.id));
    if (index === -1) {
        return sendError(res, 404, 'not_found', 'Task not found');
    }
    tasks.splice(index, 1);
    res.status(204).end();
});

export default router;