apimo.js 1.0.1

package/src/services/storage/filesystem.cache.ts

@@ -0,0 +1,94 @@
+import type { CatalogName } from '../../consts/catalogs'
+import type { ApiCulture } from '../../consts/languages'
+import type { CatalogEntry } from '../../schemas/common'
+import type { ApiCacheAdapter, CatalogEntryName } from './types'
+import { mkdirSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import * as path from 'node:path'
+import { CacheExpiredError } from './types'
+
+const DEFAULT_FILESYSTEM_CACHE_LOCATION = './cache/catalogs'
+const MS_IN_ONE_WEEK = 7 * 24 * 60 * 60 * 1000
+
+export class FilesystemCache implements ApiCacheAdapter {
+  private readonly path: string
+  private readonly cacheExpirationMs: number
+
+  constructor(settings?: { path?: string, cacheExpirationMs?: number }) {
+    this.path = settings?.path ?? DEFAULT_FILESYSTEM_CACHE_LOCATION
+    this.cacheExpirationMs = settings?.cacheExpirationMs ?? MS_IN_ONE_WEEK
+
+    mkdirSync(this.path, { recursive: true })
+  }
+
+  async setEntries(catalogName: CatalogName, culture: ApiCulture, entries: CatalogEntry[]): Promise<void> {
+    const filePath = this.getCacheFilePath(catalogName, culture)
+    const formattedEntries = Object.fromEntries(
+      entries.map<[
+        string,
+        CatalogEntryName,
+      ]>(({ id, name, name_plurial }) => [id.toString(), {
+        name,
+        namePlural: name_plurial,
+      }]),
+    )
+    const dump = JSON.stringify({
+      timestamp: Date.now(),
+      cache: formattedEntries,
+    })
+    return writeFile(filePath, dump)
+  }
+
+  async readFileOrThrow(filePath: string): Promise<string> {
+    try {
+      return await readFile(filePath, 'utf-8')
+    }
+    catch {
+      throw new CacheExpiredError()
+    }
+  }
+
+  async getEntry(catalogName: CatalogName, culture: ApiCulture, id: number): Promise<CatalogEntryName | null> {
+    const filePath = this.getCacheFilePath(catalogName, culture)
+    const data = await this.readFileOrThrow(filePath)
+    const parsed: {
+      timestamp: number
+      cache: { [id: string]: CatalogEntryName | undefined }
+    } = JSON.parse(data)
+
+    const currentTimestamp = Date.now()
+    if (parsed.timestamp + this.cacheExpirationMs < currentTimestamp) {
+      throw new CacheExpiredError()
+    }
+
+    return parsed.cache[id.toString()] ?? null
+  }
+
+  async getEntries(catalogName: CatalogName, culture: ApiCulture): Promise<CatalogEntry[]> {
+    const filePath = this.getCacheFilePath(catalogName, culture)
+    const data = await this.readFileOrThrow(filePath)
+    const parsed: {
+      timestamp: number
+      cache: { [id: string]: CatalogEntryName | undefined }
+    } = JSON.parse(data)
+
+    const currentTimestamp = Date.now()
+    if (parsed.timestamp + this.cacheExpirationMs < currentTimestamp) {
+      throw new CacheExpiredError()
+    }
+
+    return Object.entries(parsed.cache).map(([id, entry]) => ({
+      id: Number.parseInt(id, 10),
+      name: entry?.name ?? 'missing',
+      name_plurial: entry?.namePlural,
+    }))
+  }
+
+  private getCacheFilePath(catalogName: CatalogName, culture: ApiCulture) {
+    return path.join(this.path, this.getCacheFileName(catalogName, culture))
+  }
+
+  private getCacheFileName(catalogName: CatalogName, culture: ApiCulture) {
+    return `${catalogName}-${culture}.json`
+  }
+}

package/src/services/storage/memory.cache.test.ts

@@ -0,0 +1,94 @@
+import type { CatalogName } from '../../consts/catalogs'
+import type { ApiCulture } from '../../consts/languages'
+import { describe, expect, it } from 'vitest'
+import { MemoryCache } from './memory.cache'
+
+describe('cache - Memory', () => {
+  describe('constructor', () => {
+    it('should use default expiration time when no settings provided', () => {
+      const defaultCache = new MemoryCache()
+      expect(defaultCache.cacheExpirationMs).toBe(7 * 24 * 60 * 60 * 1000)
+    })
+
+    it('should use custom expiration time when provided', () => {
+      const customExpiration = 60000
+      const customCache = new MemoryCache({ cacheExpirationMs: customExpiration })
+      expect(customCache.cacheExpirationMs).toBe(customExpiration)
+    })
+  })
+
+  describe('setEntries and getEntry', () => {
+    const culture: ApiCulture = 'en'
+    const entries = [
+      { id: 1, name: 'Item 1', name_plurial: 'Items 1' },
+      { id: 2, name: 'Item 2', name_plurial: 'Items 2' },
+    ]
+
+    it('should store and retrieve entries correctly', async () => {
+      const cache = new MemoryCache()
+      const catalogName: CatalogName = 'book_step'
+      await cache.setEntries(catalogName, culture, entries)
+
+      const entry1 = await cache.getEntry(catalogName, culture, 1)
+      const entry2 = await cache.getEntry(catalogName, culture, 2)
+
+      expect(entry1).toEqual({ name: 'Item 1', namePlural: 'Items 1' })
+      expect(entry2).toEqual({ name: 'Item 2', namePlural: 'Items 2' })
+    })
+
+    it('should return null for non-existent entry', async () => {
+      const cache = new MemoryCache()
+      const catalogName: CatalogName = 'book_step'
+      await cache.setEntries(catalogName, culture, entries)
+
+      const entry = await cache.getEntry(catalogName, culture, 999)
+      expect(entry).toBeNull()
+    })
+
+    it('should throw CacheExpiredError when cache entry does not exist', async () => {
+      const cache = new MemoryCache()
+      const catalogName: CatalogName = 'book_step'
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrowError()
+    })
+
+    it('should throw CacheExpiredError when cache has expired', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const expiredCache = new MemoryCache({ cacheExpirationMs: 1 })
+      await expiredCache.setEntries(catalogName, culture, entries)
+
+      await new Promise(resolve => setTimeout(resolve, 10))
+
+      await expect(expiredCache.getEntry(catalogName, culture, 1)).rejects.toThrowError()
+    })
+
+    it('should handle different catalog and culture combinations', async () => {
+      const cache = new MemoryCache()
+      await cache.setEntries('book_step', 'en', entries)
+      await cache.setEntries('property_land', 'fr', entries)
+
+      const entry1 = await cache.getEntry('book_step', 'en', 1)
+      const entry2 = await cache.getEntry('property_land', 'fr', 1)
+
+      expect(entry1).toEqual({ name: 'Item 1', namePlural: 'Items 1' })
+      expect(entry2).toEqual({ name: 'Item 1', namePlural: 'Items 1' })
+
+      await expect(cache.getEntry('book_step', 'fr', 1)).rejects.toThrowError()
+    })
+
+    it('should overwrite existing cache when setting new entries', async () => {
+      const cache = new MemoryCache()
+      const catalogName: CatalogName = 'property_land'
+
+      await cache.setEntries(catalogName, culture, entries)
+
+      const newEntries = [{ id: 3, name: 'New Item', name_plurial: 'New Items' }]
+      await cache.setEntries(catalogName, culture, newEntries)
+
+      const newEntry = await cache.getEntry(catalogName, culture, 3)
+      expect(newEntry).toEqual({ name: 'New Item', namePlural: 'New Items' })
+
+      const oldEntry = await cache.getEntry(catalogName, culture, 1)
+      expect(oldEntry).toBeNull()
+    })
+  })
+})

package/src/services/storage/memory.cache.ts

@@ -0,0 +1,69 @@
+import type { CatalogName } from '../../consts/catalogs'
+import type { ApiCulture } from '../../consts/languages'
+import type { CatalogEntry } from '../../schemas/common'
+import type { ApiCacheAdapter, CatalogEntryName } from './types'
+import { CacheExpiredError } from './types'
+
+const MS_IN_ONE_WEEK = 7 * 24 * 60 * 60 * 1000
+
+type Memory = Map<string, {
+  timestamp: number
+  cache: Map<number, CatalogEntryName>
+}>
+
+export class MemoryCache implements ApiCacheAdapter {
+  readonly cacheExpirationMs: number
+  readonly _MEMORY: Memory
+
+  constructor(settings?: { cacheExpirationMs?: number }) {
+    this.cacheExpirationMs = settings?.cacheExpirationMs ?? MS_IN_ONE_WEEK
+    this._MEMORY = new Map()
+  }
+
+  async setEntries(catalogName: CatalogName, culture: ApiCulture, entries: CatalogEntry[]): Promise<void> {
+    const memoryEntry = new Map(
+      entries.map<[number, CatalogEntryName]>(({ id, name, name_plurial }) => [id, {
+        name,
+        namePlural: name_plurial,
+      }]),
+    )
+    this._MEMORY.set(this.getCacheKey(catalogName, culture), {
+      timestamp: Date.now(),
+      cache: memoryEntry,
+    })
+  }
+
+  async getEntry(catalogName: CatalogName, culture: ApiCulture, id: number) {
+    const memoryEntry = this._MEMORY.get(this.getCacheKey(catalogName, culture))
+
+    if (!memoryEntry) {
+      throw new CacheExpiredError()
+    }
+    if (memoryEntry.timestamp + this.cacheExpirationMs < Date.now()) {
+      throw new CacheExpiredError()
+    }
+
+    return memoryEntry.cache.get(id) ?? null
+  }
+
+  async getEntries(catalogName: CatalogName, culture: ApiCulture): Promise<CatalogEntry[]> {
+    const memoryEntry = this._MEMORY.get(this.getCacheKey(catalogName, culture))
+
+    if (!memoryEntry) {
+      throw new CacheExpiredError()
+    }
+    if (memoryEntry.timestamp + this.cacheExpirationMs < Date.now()) {
+      throw new CacheExpiredError()
+    }
+
+    return Array.from(memoryEntry.cache.entries()).map(([id, { name, namePlural }]) => ({
+      id,
+      name,
+      name_plurial: namePlural,
+    }))
+  }
+
+  private getCacheKey(catalogName: CatalogName, culture: ApiCulture) {
+    return `${catalogName}.${culture}`
+  }
+}

package/src/services/storage/types.ts

@@ -0,0 +1,20 @@
+import type { CatalogName } from '../../consts/catalogs'
+import type { ApiCulture } from '../../consts/languages'
+import type { CatalogEntry } from '../../schemas/common'
+
+export interface CatalogEntryName {
+  name: string
+  namePlural: string | undefined
+}
+
+export interface ApiCacheAdapter {
+  setEntries: (catalogName: CatalogName, culture: ApiCulture, entries: CatalogEntry[]) => Promise<void>
+  getEntry: (catalogName: CatalogName, culture: ApiCulture, id: number) => Promise<CatalogEntryName | null>
+  getEntries: (catalogName: CatalogName, culture: ApiCulture) => Promise<CatalogEntry[]>
+}
+
+export class CacheExpiredError extends Error {
+}
+
+export class NotInCacheError extends Error {
+}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export type LACK_OF_DOCUMENTATION = string
+
+export type DeepPartial<T> = T extends object ? {
+  [P in keyof T]?: DeepPartial<T[P]>;
+} : T

package/src/utils/url.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_ADDITIONAL_CONFIG } from '../core/api'
+import { makeApiUrl } from './url'
+
+const CONFIG = DEFAULT_ADDITIONAL_CONFIG
+describe('url util', () => {
+  it('should, given an array of parts return a complete url', () => {
+    const url = makeApiUrl(['hello', 'world'], CONFIG)
+    expect(url.href).toBe('https://api.apimo.pro/hello/world')
+  })
+
+  it('should, given an array of parts and search params return a complete url', () => {
+    const url = makeApiUrl(['hello', 'world'], CONFIG, { culture: 'fr', limit: 10 })
+    expect(url.href).toBe('https://api.apimo.pro/hello/world?culture=fr&limit=10')
+  })
+
+  it('should, given an array of parts and search params with undefined values, ignore them', () => {
+    const url = makeApiUrl(['hello', 'world'], CONFIG, { culture: 'fr', limit: undefined })
+    expect(url.href).toBe('https://api.apimo.pro/hello/world?culture=fr')
+  })
+})

package/src/utils/url.ts

@@ -0,0 +1,27 @@
+import type { ApiCulture } from '../consts/languages'
+import type { AdditionalConfig } from '../core/api'
+import type { LACK_OF_DOCUMENTATION } from '../types'
+
+export interface ApiSearchParams {
+  culture?: ApiCulture
+  limit?: number
+  offset?: number
+  timestamp?: number
+  step?: LACK_OF_DOCUMENTATION
+  status?: LACK_OF_DOCUMENTATION
+  group?: LACK_OF_DOCUMENTATION
+
+  [key: string]: string | number | undefined
+}
+
+export function makeApiUrl(pathParts: string[], config: AdditionalConfig, searchParams?: Partial<ApiSearchParams>): URL {
+  const url = new URL(pathParts.join('/'), config.baseUrl)
+  if (searchParams) {
+    Object.entries(searchParams).forEach(([key, value]) => {
+      if (value !== undefined) {
+        url.searchParams.append(key, value.toString())
+      }
+    })
+  }
+  return url
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es2015",
+    "module": "es2015",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    setupFiles: ['dotenv/config'],
+  },
+})