Rename @cached to @memoized (#4)

Author: ayaka14732

src/__tests__/helper.test.ts

@@ -1,13 +1,13 @@
 import { describe, it, expect, vi } from 'vitest';
 
-import { cached } from '../utils/helper';
+import { memoized } from '../utils/helper';
 
-describe('cached decorator', () => {
+describe('memoized decorator', () => {
   it('should evaluate the getter only once per instance', () => {
     const compute = vi.fn(() => 42);
 
     class Test {
-      @cached
+      @memoized
       get value() {
         return compute();
       }
@@ -17,17 +17,17 @@ describe('cached decorator', () => {
 
     // first access: compute
     expect(a.value).toBe(42);
-    // second access: cached
+    // second access: memoized
     expect(a.value).toBe(42);
 
     expect(compute).toHaveBeenCalledTimes(1);
   });
 
-  it('should cache per instance, not shared across instances', () => {
+  it('should memoize per instance, not shared across instances', () => {
     let callCount = 0;
 
     class Test {
-      @cached
+      @memoized
       get value() {
         callCount++;
         return callCount;
@@ -42,7 +42,7 @@ describe('cached decorator', () => {
     const b1 = b.value;
 
     expect(a1).toBe(1);
-    expect(a2).toBe(1); // cached on same instance
+    expect(a2).toBe(1); // memoized on same instance
     expect(b1).toBe(2); // separate instance → separate evaluation
     expect(callCount).toBe(2);
   });
@@ -51,7 +51,7 @@ describe('cached decorator', () => {
     class Test {
       public _count = 0;
 
-      @cached
+      @memoized
       get value() {
         this._count++;
         return this._count;

src/core/韻鏡位置.ts

@@ -1,7 +1,7 @@
 import { defaultLogger, 音韻地位 } from 'tshet-uinh';
 
 import { 母位置名稱, 轉名稱列表, 轉呼 } from '../utils/常量';
-import { cached } from '../utils/helper';
+import { memoized } from '../utils/helper';
 
 // import { 等韻搭配, 鈍音母 } from './音韻屬性常量';
 /** 依可搭配的等列出各韻 */
@@ -57,27 +57,27 @@ class 韻鏡位置 {
 
   /**
    * 轉的名稱（如「內轉第一圖」）。
-  */
-  @cached
+   */
+  @memoized
   get 轉名稱() {
     return `${轉名稱列表[this.轉號 - 1]}圖`;
   }
 
   /**
    * 坐標的字串表示（如「(1,1,1)」）。
-  */
-  @cached
+   */
+  @memoized
   get 坐標() {
     const { 轉號, 上位, 右位 } = this;
     return `(${轉號},${上位},${右位})`;
   }
 
   /**
    * 韻鏡等（「一二三四」）。
-  *
-  * 僅由上位決定，與切韻等未必一致。
-  */
-  @cached
+   *
+   * 僅由上位決定，與切韻等未必一致。
+   */
+  @memoized
   get 韻鏡等() {
     const { 上位 } = this;
     const 韻鏡等 = ((上位 - 1) % 4) + 1;
@@ -91,7 +91,7 @@ class 韻鏡位置 {
    *
    * 與《韻鏡》標註的韻亦未必一致，因為存在一些特殊情況，例如《韻鏡》原書存在刪、山韻排反的情況，此處均已進行修正。
    */
-  @cached
+  @memoized
   get 韻() {
     const { 轉號, 上位, 右位 } = this;
     return 轉號上位右位2韻(轉號, 上位, 右位);
@@ -100,7 +100,7 @@ class 韻鏡位置 {
   /**
    * 切韻等（「一二三四」）。
    */
-  @cached
+  @memoized
   get 切韻等() {
     const { 轉號, 上位, 右位, 韻鏡等, 韻 } = this;
 
@@ -137,7 +137,7 @@ class 韻鏡位置 {
   /**
    * 韻鏡母。
    */
-  @cached
+  @memoized
   get 母() {
     const { 右位, 韻鏡等, 切韻等 } = this;
 
@@ -223,7 +223,7 @@ class 韻鏡位置 {
    *
    * 與《韻鏡》標註的呼未必一致，例如包含 `null`，又如《韻鏡》原書第四轉標註為「內轉第四開合」，而此處為「開」。
    */
-  @cached
+  @memoized
   get 呼() {
     const { 轉號, 轉名稱, 韻, 母 } = this;
     if ([...'幫滂並明'].includes(母) || [...'模侯尤'].includes(韻)) {
@@ -241,7 +241,7 @@ class 韻鏡位置 {
    *
    * 由上位推得，並根據「去聲寄此」的韻鏡標註修正。
    */
-  @cached
+  @memoized
   get 聲() {
     const { 轉號, 上位 } = this;
     const raw聲 = [...'平上去入'][Math.floor((上位 - 1) / 4)];
@@ -256,7 +256,7 @@ class 韻鏡位置 {
   /**
    * 切韻類（A/B/C/`null`）。
    */
-  @cached
+  @memoized
   get 類() {
     const { 韻鏡等, 切韻等, 韻, 母 } = this;
     if (切韻等 !== '三' || !鈍音母.includes(母)) {
@@ -298,7 +298,7 @@ class 韻鏡位置 {
   /**
    * 韻鏡位置描述（如「外轉第四十二圖·舌音第一位·入聲位·韻鏡一等」）。
    */
-  @cached
+  @memoized
   get 描述() {
     const { 上位, 右位, 轉名稱, 韻鏡等 } = this;
     const raw聲 = [...'平上去入'][Math.floor((上位 - 1) / 4)];

src/utils/helper.ts

@@ -1,29 +1,32 @@
 type AnyGetter<T, R> = (this: T) => R;
 
 /**
- * Cache a getter result per-instance.
- * - Stores cache in a non-enumerable, per-decorator Symbol to avoid collisions.
+ * Memoize a getter result per instance.
+ * - Stores the memoized value in a non-enumerable, per-decorator Symbol to avoid collisions.
  * - Works with TS 5.x / new decorators (ClassGetterDecoratorContext).
  * - Pure getters only: if underlying state changes, you must provide invalidation yourself.
  */
-export function cached<T extends object, R>(originalGetter: AnyGetter<T, R>, context: ClassGetterDecoratorContext<T, R>): AnyGetter<T, R> {
+export function memoized<T extends object, R>(
+  originalGetter: AnyGetter<T, R>,
+  context: ClassGetterDecoratorContext<T, R>,
+): AnyGetter<T, R> {
   if (context.kind !== 'getter') {
-    throw new TypeError('@cached can only be applied to a getter.');
+    throw new TypeError('@memoized can only be applied to a getter.');
   }
 
   // One unique key per decorated getter (per class definition).
-  const cacheKey = Symbol(`@cached:${String(context.name)}`);
+  const memoKey = Symbol(`@memoized:${String(context.name)}`);
 
   return function (this: T): R {
     // Use hasOwnProperty so prototype chain doesn't interfere.
-    if (Object.prototype.hasOwnProperty.call(this, cacheKey)) {
-      return (this as any)[cacheKey] as R;
+    if (Object.prototype.hasOwnProperty.call(this, memoKey)) {
+      return (this as any)[memoKey] as R;
     }
 
     const value = originalGetter.call(this);
 
     // Define as non-enumerable to avoid polluting iteration/serialization/debug output.
-    Object.defineProperty(this, cacheKey, {
+    Object.defineProperty(this, memoKey, {
       value,
       writable: true, // allow manual override if needed
       configurable: true, // allow manual deletion to invalidate