TypeScript 与接口契约

type CreateTaskResult =
  | { kind: 'created'; taskId: string }
  | { kind: 'validation_error'; field: string; message: string }
  | { kind: 'forbidden'; message: string };

function describe(result: CreateTaskResult): string {
  switch (result.kind) {
    case 'created':
      return `任务已创建：${result.taskId}`;
    case 'validation_error':
      return `${result.field}：${result.message}`;
    case 'forbidden':
      return result.message;
    default: {
      // 添加新分支却忘了更新处理逻辑时，类型检查会报错。
      const unreachable: never = result;
      return unreachable;
    }
  }
}

import assert from 'node:assert/strict';

function parseCreateTask(input) {
  // JSON.parse 后仍是外部数据，先排除 null 和数组。
  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
    throw new TypeError('请求体必须是对象');
  }
  const allowedKeys = new Set(['title', 'priority']);
  if (Object.keys(input).some(key => !allowedKeys.has(key))) {
    throw new TypeError('存在不支持的字段');
  }
  if (typeof input.title !== 'string') {
    throw new TypeError('title 必须是字符串');
  }
  const title = input.title.trim();
  // 此处使用 Unicode 码点计数，不等同于用户感知的字符簇数量。
  if ([...title].length < 1 || [...title].length > 80) {
    throw new TypeError('title 长度应为 1 到 80 个码点');
  }
  const priority = input.priority ?? 'normal';
  if (!['low', 'normal', 'high'].includes(priority)) {
    throw new TypeError('priority 不在允许范围内');
  }
  // 显式创建新对象，只向后续业务层传递已经校验的字段。
  return { title, priority };
}

assert.deepEqual(parseCreateTask({ title: '  阅读事务章节  ' }), {
  title: '阅读事务章节', priority: 'normal',
});
assert.throws(() => parseCreateTask({ title: '  ' }), /title/);
assert.throws(() => parseCreateTask({ title: '任务', ownerId: 'someone' }), /字段/);
console.log('输入校验通过：正常、空值、额外字段三类场景');

import assert from 'node:assert/strict';

function parseDateOnly(value) {
  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
    throw new TypeError('DATE_FORMAT');
  }
  const [year, month, day] = value.split('-').map(Number);
  if (year < 1 || month < 1 || month > 12) throw new TypeError('DATE_RANGE');
  const leap = year % 400 === 0 || (year % 4 === 0 && year % 100 !== 0);
  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
  if (day < 1 || day > days[month - 1]) throw new TypeError('DATE_RANGE');
  return value; // 不隐式转换为某个时区的午夜时间。
}

function parseTask(input) {
  if (!input || typeof input !== 'object' || Array.isArray(input)) {
    throw new TypeError('BODY_OBJECT_REQUIRED');
  }
  const allowed = new Set(['title', 'priority', 'dueDate']);
  if (Object.keys(input).some(key => !allowed.has(key))) throw new TypeError('UNKNOWN_FIELD');
  if (typeof input.title !== 'string') throw new TypeError('TITLE_TYPE');
  const title = input.title.trim();
  if ([...title].length < 1 || [...title].length > 80) throw new TypeError('TITLE_LENGTH');
  // 这个版本只有缺失值使用默认值，明确拒绝 null。
  const priority = input.priority === undefined ? 'normal' : input.priority;
  if (!['low', 'normal', 'high'].includes(priority)) throw new TypeError('PRIORITY_RANGE');
  const dueDate = input.dueDate === undefined ? null : parseDateOnly(input.dueDate);
  return { title, priority, dueDate };
}

function ensureNotPast(dueDate, today) {
  parseDateOnly(today);
  if (dueDate !== null && parseDateOnly(dueDate) < today) {
    throw new Error('DUE_DATE_IN_PAST');
  }
}

assert.equal(parseDateOnly('2028-02-29'), '2028-02-29');
assert.throws(() => parseDateOnly('2026-02-30'), /DATE_RANGE/);
assert.throws(() => parseDateOnly('1900-02-29'), /DATE_RANGE/);
assert.equal(parseDateOnly('2000-02-29'), '2000-02-29');
assert.throws(() => parseDateOnly('2026-9-1'), /DATE_FORMAT/);
assert.throws(() => parseTask({ title: '检查权限', priority: null }), /PRIORITY_RANGE/);
const task = parseTask({ title: '  检查权限  ', dueDate: '2026-09-11' });
assert.equal(task.title, '检查权限');
ensureNotPast(task.dueDate, '2026-09-10');
assert.throws(() => ensureNotPast('2026-09-09', '2026-09-10'), /IN_PAST/);
console.log('通过：日期格式、闰年、默认值、规范化与独立业务规则');

import assert from 'node:assert/strict';

function parsePatch(input) {
  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('BODY');
  const allowed = new Set(['title', 'description']);
  if (Object.keys(input).some(key => !allowed.has(key))) throw new TypeError('UNKNOWN_FIELD');
  const patch = {};
  if (Object.hasOwn(input, 'title')) {
    if (typeof input.title !== 'string' || !input.title.trim()) throw new TypeError('TITLE');
    if ([...input.title.trim()].length > 80) throw new TypeError('TITLE');
    patch.title = input.title.trim();
  }
  if (Object.hasOwn(input, 'description')) {
    if (input.description !== null && typeof input.description !== 'string') throw new TypeError('DESCRIPTION');
    if (typeof input.description === 'string' && input.description.length > 2000) throw new TypeError('DESCRIPTION');
    patch.description = input.description;
  }
  if (!Object.keys(patch).length) throw new TypeError('EMPTY_PATCH');
  return patch;
}

const old = { id: 'task-1', title: '旧标题', description: '应保留的说明', ownerId: 'alice' };
assert.equal(({ ...old, ...parsePatch({ title: '新标题' }) }).description, old.description);
assert.equal(({ ...old, ...parsePatch({ description: null }) }).description, null);
assert.equal(({ ...old, ...parsePatch({ description: '' }) }).description, '');
assert.throws(() => parsePatch({ title: null }), /TITLE/);
assert.throws(() => parsePatch({ ownerId: 'bob' }), /UNKNOWN_FIELD/);
assert.throws(() => parsePatch({}), /EMPTY_PATCH/);
console.log('通过：未修改、显式清空、空字符串、非法字段和空更新');