Объясните декораторы (decorators) в TypeScript: что это, как работает и когда применять.

// Legacy method decorator: (target, propertyKey, descriptor)
function logged(_t: unknown, key: string, desc: PropertyDescriptor) {
  const orig = desc.value;
  desc.value = function (...args: unknown[]) {
    console.log(`→ ${key}`, args);
    return orig.apply(this, args);
  };
}

// Stage 3 method decorator: (value, context)
function logged<T extends (...a: any[]) => any>(
  orig: T,
  ctx: ClassMethodDecoratorContext
) {
  return function (this: unknown, ...args: Parameters<T>) {
    console.log(`→ ${String(ctx.name)}`, args);
    return orig.call(this, ...args);
  } as T;
}

// Same intent, both worlds. Legacy mutates the descriptor in place:
class ApiLegacy {
  @logged                     // experimentalDecorators: true
  fetch(id: string) { /* ... */ }
}

// Stage 3 returns a replacement — no descriptor mutation, no flags:
class ApiModern {
  @logged                     // TS 5.0 default
  fetch(id: string) { /* ... */ }
}

// Class decorator returning a subclass (Stage 3) — the "replace the declaration" power
function withId<T extends new (...a: any[]) => object>(Base: T, _c: ClassDecoratorContext) {
  return class extends Base {
    id = crypto.randomUUID();
  };
}
@withId class Widget {}
// new Widget().id is present at runtime, but note: the added field
// is NOT visible on the static type unless you also declare it.