@gravito/cosmos 3.2.2 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/cosmos",
-  "version": "3.2.2",
+  "version": "4.0.0",
   "description": "Internationalization orbit for Gravito framework",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -43,8 +43,8 @@
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
   "peerDependencies": {
-    "@gravito/core": "^2.0.0",
-    "@gravito/photon": "^1.1.0"
+    "@gravito/core": "^3.0.0",
+    "@gravito/photon": "^2.0.0"
   },
   "devDependencies": {
     "@gravito/core": "workspace:*",

package/src/I18nService.ts

@@ -7,6 +7,8 @@
 import type { GravitoMiddleware } from '@gravito/core'
 import { LRUCache } from 'lru-cache'
 import { type HMRConfig, HMRWatcher } from './HMRWatcher'
+import { CosmosError } from './errors/CosmosError'
+import { CosmosErrorCodes } from './errors/codes'
 import { loadLocale } from './loader'
 import type { TranslationLoader } from './loaders/TranslationLoader'
 
@@ -816,7 +818,9 @@ export class I18nManager<Schema = TranslationMap> implements I18nService<Schema>
       case 'empty':
         return ''
       case 'throw':
-        throw new Error(`Missing translation: ${key}`)
+        throw new CosmosError(500, CosmosErrorCodes.MISSING_TRANSLATION, {
+          message: `Missing translation: ${key}`,
+        })
       default:
         return key
     }

package/src/errors/CosmosError.ts

@@ -0,0 +1,20 @@
+import { SystemException, type ExceptionOptions } from '@gravito/core'
+import type { CosmosErrorCode } from './codes'
+
+/**
+ * Base error class for @gravito/cosmos i18n operations.
+ * Extends SystemException as cosmos is a general system utility (not a domain/auth module).
+ *
+ * @public
+ */
+export class CosmosError extends SystemException {
+  constructor(
+    status: number,
+    code: CosmosErrorCode,
+    options: ExceptionOptions = {}
+  ) {
+    super(status, code, options)
+    this.name = 'CosmosError'
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}

package/src/errors/codes.ts

@@ -0,0 +1,30 @@
+/**
+ * Structured error codes for @gravito/cosmos i18n operations.
+ * Follows the dot-separated namespace convention used across Gravito.
+ *
+ * @public
+ */
+export const CosmosErrorCodes = {
+  // Translation errors
+  MISSING_TRANSLATION: 'cosmos.missing_translation',
+
+  // Loader errors
+  LOADER_FAILED: 'cosmos.loader_failed',
+  UNSUPPORTED_FORMAT: 'cosmos.unsupported_format',
+
+  // Filesystem loader errors
+  FILE_NOT_FOUND: 'cosmos.file_not_found',
+  FILE_READ_FAILED: 'cosmos.file_read_failed',
+
+  // Remote loader errors
+  HTTP_ERROR: 'cosmos.http_error',
+
+  // Runtime errors
+  EDGE_RUNTIME_UNSUPPORTED: 'cosmos.edge_runtime_unsupported',
+
+  // KV storage errors
+  KV_PUT_UNSUPPORTED: 'cosmos.kv_put_unsupported',
+  KV_DELETE_UNSUPPORTED: 'cosmos.kv_delete_unsupported',
+} as const
+
+export type CosmosErrorCode = (typeof CosmosErrorCodes)[keyof typeof CosmosErrorCodes]

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export { CosmosError } from './CosmosError'
+export { CosmosErrorCodes, type CosmosErrorCode } from './codes'

package/src/index.ts

@@ -94,3 +94,6 @@ export * from './loaders/VercelKVLoader'
 // Runtime utilities
 export * from './runtime/detector'
 export * from './runtime/path-utils'
+
+// Errors
+export * from './errors'

package/src/loader.ts

@@ -21,6 +21,8 @@
 
 import { readdir, readFile } from 'node:fs/promises'
 import { join, parse } from 'node:path'
+import { CosmosError } from './errors/CosmosError'
+import { CosmosErrorCodes } from './errors/codes'
 
 /**
  * 偵測 Bun 運行時是否原生支援 JSON5 解析
@@ -56,10 +58,11 @@ async function parseJson5(content: string): Promise<unknown> {
     const json5 = json5Module.default ?? json5Module
     return (json5 as { parse: (text: string) => unknown }).parse(content)
   } catch {
-    throw new Error(
-      '[Cosmos] JSON5 parsing requires either Bun v1.2+ or the `json5` npm package. ' +
-        'Please install it: bun add json5'
-    )
+    throw new CosmosError(500, CosmosErrorCodes.UNSUPPORTED_FORMAT, {
+      message:
+        '[Cosmos] JSON5 parsing requires either Bun v1.2+ or the `json5` npm package. ' +
+        'Please install it: bun add json5',
+    })
   }
 }
 

package/src/loaders/EdgeKVLoader.ts

@@ -5,6 +5,8 @@
  */
 
 import type { TranslationMap } from '../I18nService'
+import { CosmosError } from '../errors/CosmosError'
+import { CosmosErrorCodes } from '../errors/codes'
 import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
 
 /**
@@ -219,7 +221,9 @@ export class EdgeKVLoader implements TranslationLoaderChain {
    */
   async put(locale: string, translations: TranslationMap): Promise<void> {
     if (!this.storage.put) {
-      throw new Error('[EdgeKVLoader] Storage does not support put operation')
+      throw new CosmosError(500, CosmosErrorCodes.KV_PUT_UNSUPPORTED, {
+        message: '[EdgeKVLoader] Storage does not support put operation',
+      })
     }
 
     const key = this.buildKey(locale)
@@ -239,7 +243,9 @@ export class EdgeKVLoader implements TranslationLoaderChain {
    */
   async delete(locale: string): Promise<void> {
     if (!this.storage.delete) {
-      throw new Error('[EdgeKVLoader] Storage does not support delete operation')
+      throw new CosmosError(500, CosmosErrorCodes.KV_DELETE_UNSUPPORTED, {
+        message: '[EdgeKVLoader] Storage does not support delete operation',
+      })
     }
 
     const key = this.buildKey(locale)

package/src/loaders/FileSystemLoader.ts

@@ -19,6 +19,8 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { TranslationMap } from '../I18nService'
+import { CosmosError } from '../errors/CosmosError'
+import { CosmosErrorCodes } from '../errors/codes'
 import { detectRuntime } from '../runtime/detector'
 import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
 
@@ -96,10 +98,11 @@ export class FileSystemLoader implements TranslationLoaderChain {
     // 運行時檢查
     const runtime = detectRuntime()
     if (runtime === 'edge') {
-      throw new Error(
-        '[FileSystemLoader] This loader requires Node.js and cannot run in Edge Runtime. ' +
-          'Use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.'
-      )
+      throw new CosmosError(500, CosmosErrorCodes.EDGE_RUNTIME_UNSUPPORTED, {
+        message:
+          '[FileSystemLoader] This loader requires Node.js and cannot run in Edge Runtime. ' +
+          'Use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.',
+      })
     }
 
     this.name = config.name || 'FileSystemLoader'
@@ -161,10 +164,11 @@ export class FileSystemLoader implements TranslationLoaderChain {
       const json5 = json5Module.default ?? json5Module
       return (json5 as { parse: (text: string) => unknown }).parse(content) as TranslationMap
     } catch {
-      throw new Error(
-        '[FileSystemLoader] JSON5 parsing requires either Bun v1.2+ (native support) ' +
-          'or the `json5` npm package. Please install it: bun add json5'
-      )
+      throw new CosmosError(500, CosmosErrorCodes.UNSUPPORTED_FORMAT, {
+        message:
+          '[FileSystemLoader] JSON5 parsing requires either Bun v1.2+ (native support) ' +
+          'or the `json5` npm package. Please install it: bun add json5',
+      })
     }
   }
 

package/src/loaders/Json5Loader.ts

@@ -17,6 +17,8 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { TranslationMap } from '../I18nService'
+import { CosmosError } from '../errors/CosmosError'
+import { CosmosErrorCodes } from '../errors/codes'
 import { detectRuntime } from '../runtime/detector'
 import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
 
@@ -95,10 +97,11 @@ async function parseJson5Content(content: string): Promise<unknown> {
     const json5 = json5Module.default ?? json5Module
     return (json5 as { parse: (text: string) => unknown }).parse(content)
   } catch {
-    throw new Error(
-      '[Json5Loader] JSON5 parsing requires either Bun v1.2+ (native support) ' +
-        'or the `json5` npm package. Please install it: bun add json5'
-    )
+    throw new CosmosError(500, CosmosErrorCodes.UNSUPPORTED_FORMAT, {
+      message:
+        '[Json5Loader] JSON5 parsing requires either Bun v1.2+ (native support) ' +
+        'or the `json5` npm package. Please install it: bun add json5',
+    })
   }
 }
 
@@ -145,10 +148,11 @@ export class Json5Loader implements TranslationLoaderChain {
     // 運行時檢查
     const runtime = detectRuntime()
     if (runtime === 'edge') {
-      throw new Error(
-        '[Json5Loader] This loader requires Node.js and cannot run in Edge Runtime. ' +
-          'Use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.'
-      )
+      throw new CosmosError(500, CosmosErrorCodes.EDGE_RUNTIME_UNSUPPORTED, {
+        message:
+          '[Json5Loader] This loader requires Node.js and cannot run in Edge Runtime. ' +
+          'Use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.',
+      })
     }
 
     this.name = config.name ?? 'Json5Loader'

package/src/loaders/RemoteLoader.ts

@@ -5,6 +5,8 @@
  */
 
 import type { TranslationMap } from '../I18nService'
+import { CosmosError } from '../errors/CosmosError'
+import { CosmosErrorCodes } from '../errors/codes'
 import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
 
 /**
@@ -186,7 +188,9 @@ export class RemoteLoader implements TranslationLoaderChain {
 
       // 處理錯誤狀態碼
       if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`)
+        throw new CosmosError(response.status, CosmosErrorCodes.HTTP_ERROR, {
+          message: `HTTP error! status: ${response.status}`,
+        })
       }
 
       const data = (await response.json()) as TranslationMap

package/tests/contract/cosmos-errors.contract.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'bun:test'
+import { GravitoException, SystemException } from '@gravito/core'
+import { CosmosError } from '../../src/errors/CosmosError'
+import { CosmosErrorCodes } from '../../src/errors/codes'
+
+describe('CosmosError contract', () => {
+  it('satisfies GravitoException contract', () => {
+    const err = new CosmosError(500, CosmosErrorCodes.MISSING_TRANSLATION, {
+      message: 'Missing translation: common.welcome',
+    })
+
+    expect(err).toBeInstanceOf(Error)
+    expect(err).toBeInstanceOf(GravitoException)
+    expect(err).toBeInstanceOf(SystemException)
+    expect(err).toBeInstanceOf(CosmosError)
+
+    expect(err.code).toBe('cosmos.missing_translation')
+    expect(err.status).toBe(500)
+    expect(typeof err.code).toBe('string')
+    expect(typeof err.status).toBe('number')
+    expect(err.name).toBe('CosmosError')
+    expect(err.name).not.toBe('Error')
+  })
+
+  it('extends SystemException (not DomainException or AuthException)', () => {
+    const err = new CosmosError(500, CosmosErrorCodes.LOADER_FAILED)
+    expect(err).toBeInstanceOf(SystemException)
+  })
+
+  it('preserves message', () => {
+    const err = new CosmosError(500, CosmosErrorCodes.MISSING_TRANSLATION, {
+      message: 'Missing translation: test.key',
+    })
+    expect(err.message).toBe('Missing translation: test.key')
+  })
+
+  it('preserves cause', () => {
+    const cause = new Error('original error')
+    const err = new CosmosError(500, CosmosErrorCodes.LOADER_FAILED, { cause })
+    expect(err.cause).toBe(cause)
+  })
+
+  it('instanceof chain holds for all error codes', () => {
+    const codes = Object.values(CosmosErrorCodes)
+    for (const code of codes) {
+      const err = new CosmosError(500, code)
+      expect(err).toBeInstanceOf(CosmosError)
+      expect(err).toBeInstanceOf(SystemException)
+      expect(err).toBeInstanceOf(GravitoException)
+      expect(err).toBeInstanceOf(Error)
+      expect(err.code).toBe(code)
+    }
+  })
+
+  it('all error codes are cosmos.* namespaced', () => {
+    const codes = Object.values(CosmosErrorCodes)
+    for (const code of codes) {
+      expect(code).toMatch(/^cosmos\./)
+    }
+  })
+
+  it('CosmosErrorCodes covers expected domains', () => {
+    expect(CosmosErrorCodes.MISSING_TRANSLATION).toBe('cosmos.missing_translation')
+    expect(CosmosErrorCodes.LOADER_FAILED).toBe('cosmos.loader_failed')
+    expect(CosmosErrorCodes.UNSUPPORTED_FORMAT).toBe('cosmos.unsupported_format')
+    expect(CosmosErrorCodes.FILE_NOT_FOUND).toBe('cosmos.file_not_found')
+    expect(CosmosErrorCodes.FILE_READ_FAILED).toBe('cosmos.file_read_failed')
+    expect(CosmosErrorCodes.HTTP_ERROR).toBe('cosmos.http_error')
+    expect(CosmosErrorCodes.EDGE_RUNTIME_UNSUPPORTED).toBe('cosmos.edge_runtime_unsupported')
+    expect(CosmosErrorCodes.KV_PUT_UNSUPPORTED).toBe('cosmos.kv_put_unsupported')
+    expect(CosmosErrorCodes.KV_DELETE_UNSUPPORTED).toBe('cosmos.kv_delete_unsupported')
+  })
+})