apimo.js 1.0.1

package/src/schemas/property.ts

@@ -0,0 +1,257 @@
+import type { LocalizedCatalogTransformer } from './common'
+import { z } from 'zod'
+import { Converters } from '../core/converters'
+import { CitySchema, getUserSchema, NameIdPairSchema } from './common'
+import { TYPE_UNDOCUMENTED, TYPE_UNDOCUMENTED_NULLABLE } from './internal'
+
+export function getAgreementSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    type: z.coerce.number().transform(v => transformer('property_agreement', v)),
+    reference: z.string(),
+    start_at: z.coerce.string().transform(Converters.toDate),
+    end_at: z.coerce.string().transform(Converters.toDate),
+  })
+}
+
+export function getSurfaceSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    unit: z.coerce.number().transform(v => transformer('unit_area', v)),
+    value: z.coerce.number(),
+    total: z.coerce.number(),
+    weighted: z.coerce.number(),
+  })
+}
+
+export function getPlotSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    net_floor: z.coerce.number(),
+    land_type: z.coerce.number().transform(v => transformer('property_land', v)),
+    width: z.coerce.number(),
+    height: z.coerce.number().optional(),
+    serviced_plot: z.boolean(),
+  })
+}
+
+export function getPriceSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    value: z.coerce.number(),
+    max: z.coerce.number(),
+    fees: z.coerce.number(),
+    unit: TYPE_UNDOCUMENTED_NULLABLE,
+    period: z.coerce.number().transform(v => transformer('property_period', v)),
+    hide: z.coerce.boolean(),
+    inventory: z.number().nullable(),
+    deposit: z.number().nullable(),
+    currency: z.string().toLowerCase(),
+    commission: z.number().nullable(),
+    transfer_tax: TYPE_UNDOCUMENTED_NULLABLE,
+    contribution: TYPE_UNDOCUMENTED_NULLABLE,
+    pension: TYPE_UNDOCUMENTED_NULLABLE,
+    tenant: z.number().nullable(),
+    vat: z.boolean().nullable(),
+  })
+}
+
+export function getResidenceSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    id: z.coerce.number(),
+    type: z.coerce.number().transform(v => transformer('property_building', v)),
+    fees: z.coerce.number(),
+    period: z.coerce.number().transform(v => transformer('property_period', v)),
+    lots: z.coerce.number(),
+  })
+}
+
+export function getViewSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    type: z.coerce.number().transform(v => transformer('property_view_type', v)),
+    landscape: z.coerce.number().transform(v => transformer('property_view_landscape', v)).array(),
+  })
+}
+
+export function getConstructionSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    type: z.coerce.number().transform(v => transformer('property_construction_method', v)).array().optional(),
+    construction_year: z.coerce.number(),
+    renovation_year: z.coerce.number(),
+    renovation_cost: z.coerce.number(),
+    construction_step: z.coerce.number().transform(v => transformer('construction_step', v)),
+  })
+}
+
+export function getFloorSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    type: z.coerce.number().transform(v => transformer('property_floor', v)),
+    value: z.coerce.number(),
+    levels: z.coerce.number(),
+    floors: z.coerce.number(),
+  })
+}
+
+export function getHeatingSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+
+    device: z.coerce.number().transform(v => transformer('property_heating_device', v)),
+    devices: z.coerce.number().transform(v => transformer('property_heating_device', v)).array().nullable(),
+    access: z.coerce.number().transform(v => transformer('property_heating_access', v)),
+    type: z.coerce.number().transform(v => transformer('property_heating_type', v)),
+    types: z.coerce.number().transform(v => transformer('property_heating_type', v)).array().nullable(),
+  })
+}
+
+export function getWaterSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    hot_device: z.coerce.number().transform(v => transformer('property_hot_water_device', v)),
+    hot_access: z.coerce.number().transform(v => transformer('property_hot_water_access', v)),
+    waste: z.coerce.number().transform(v => transformer('property_waste_water', v)),
+  })
+}
+
+export const CommentSchema = z.object({
+  language: z.string(),
+  title: z.string().optional().nullable(),
+  subtitle: z.string().optional().nullable(),
+  hook: TYPE_UNDOCUMENTED_NULLABLE.optional(),
+  comment: z.string(),
+  comment_full: z.string().optional().nullable(),
+})
+
+export const PictureSchema = z.object({
+  id: z.coerce.number(),
+  rank: z.coerce.number(),
+  url: z.string(),
+  width_max: z.coerce.number(),
+  height_max: z.coerce.number(),
+  internet: z.coerce.boolean(),
+  print: z.coerce.boolean(),
+  panorama: z.coerce.boolean(),
+  child: z.coerce.number(),
+  reference: TYPE_UNDOCUMENTED_NULLABLE,
+  comments: CommentSchema.array(),
+})
+
+export function getAreaSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    type: z.coerce.number().transform(v => transformer('property_areas', v)),
+    number: z.coerce.number(),
+    area: z.coerce.number(),
+    flooring: z.coerce.number().transform(v => transformer('property_flooring', v)),
+    ceiling_height: z.number().nullable(),
+    floor: z.object({
+      type: z.coerce.number().transform(v => transformer('property_floor', v)),
+      value: z.coerce.number(),
+    }),
+    orientations: z.coerce.number().transform(v => transformer('property_orientation', v)).array(),
+    comments: CommentSchema.array(),
+    lot: z.object({
+      type: TYPE_UNDOCUMENTED_NULLABLE,
+      rank: TYPE_UNDOCUMENTED_NULLABLE,
+      name: TYPE_UNDOCUMENTED.array(),
+    }),
+  })
+}
+
+export function getRegulationSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    type: z.coerce.number().transform(v => transformer('property_regulation', v)),
+    value: z.coerce.string().transform((v) => {
+      const values = v.split(',')
+      return values.map(value => Number.parseInt(value))
+    }),
+    date: z.string().transform(Converters.toDate).nullable(),
+    graph: z.string().nullable(),
+  })
+}
+
+export function getPropertySchema(transformer: LocalizedCatalogTransformer) {
+  return z.object(
+    {
+      id: z.coerce.number(),
+      reference: z.number(),
+      agency: z.coerce.number(),
+      brand: TYPE_UNDOCUMENTED_NULLABLE,
+      sector: TYPE_UNDOCUMENTED_NULLABLE,
+      user: getUserSchema(transformer),
+      step: z.number().transform(v => transformer('property_step', v)),
+      status: z.number().transform(v => transformer('property_status', v)),
+      parent: z.number().nullable(),
+      ranking: TYPE_UNDOCUMENTED_NULLABLE,
+      category: z.coerce.number().transform(v => transformer('property_category', v)),
+      name: z.string().nullable(),
+      type: z.coerce.number().transform(v => transformer('property_type', v)),
+      subtype: z.coerce.number().transform(v => transformer('property_subtype', v)),
+      agreement: getAgreementSchema(transformer).nullable(),
+      block_name: z.string().nullable(),
+      lot_reference: z.string().nullable(),
+      cadastre_reference: z.string().nullable(),
+      stairs_reference: z.string().nullable(),
+      address: z.string().nullable(),
+      address_more: z.string().nullable(),
+      publish_address: z.coerce.boolean(),
+      country: z.string().toLowerCase(),
+      region: NameIdPairSchema,
+      city: CitySchema,
+      original_city: TYPE_UNDOCUMENTED_NULLABLE,
+      district: NameIdPairSchema.nullable(),
+      original_district: TYPE_UNDOCUMENTED_NULLABLE,
+      location: TYPE_UNDOCUMENTED_NULLABLE,
+      longitude: z.coerce.number(),
+      latitude: z.coerce.number(),
+      radius: z.coerce.number(),
+      altitude: z.coerce.number(),
+      referral: TYPE_UNDOCUMENTED_NULLABLE,
+      subreferral: TYPE_UNDOCUMENTED_NULLABLE,
+      area: getSurfaceSchema(transformer),
+      plot: getPlotSchema(transformer),
+      rooms: z.coerce.number(),
+      bedrooms: z.coerce.number(),
+      sleeps: z.coerce.number(),
+      price: getPriceSchema(transformer),
+      rates: z.unknown().array(),
+      owner: TYPE_UNDOCUMENTED_NULLABLE,
+      visit: TYPE_UNDOCUMENTED_NULLABLE,
+      residence: getResidenceSchema(transformer).nullable(),
+      view: getViewSchema(transformer).nullable(),
+      construction: getConstructionSchema(transformer),
+      floor: getFloorSchema(transformer),
+      heating: getHeatingSchema(transformer),
+      water: getWaterSchema(transformer),
+      condition: z.coerce.number().transform(v => transformer('property_condition', v)),
+      standing: z.coerce.number().transform(v => transformer('property_standing', v)),
+      style: z.object({ name: z.string().nullable() }),
+      twinned: z.coerce.number().nullable(),
+      facades: z.coerce.number(),
+      length: z.coerce.number().nullable(),
+      height: z.coerce.number().nullable(),
+      url: z.string().nullable(),
+      availability: z.coerce.number().transform(v => transformer('property_availability', v)),
+      available_at: TYPE_UNDOCUMENTED_NULLABLE,
+      delivered_at: z.string().transform(Converters.toDate).nullable(),
+      activities: z.coerce.number().transform(v => transformer('property_activity', v)).array(),
+      orientations: z.coerce.number().transform(v => transformer('property_orientation', v)).array(),
+      services: z.coerce.number().transform(v => transformer('property_service', v)).array(),
+      proximities: z.coerce.number().transform(v => transformer('property_proximity', v)).array(),
+      tags: z.coerce.number().transform(v => transformer('tags', v)).array(),
+      tags_customized: z.unknown().array(),
+      pictures: PictureSchema.array(),
+      medias: z.unknown().array(),
+      documents: z.unknown().array(),
+      comments: CommentSchema.array(),
+      areas: getAreaSchema(transformer).array(),
+      regulations: getRegulationSchema(transformer).array(),
+      financial: z.unknown().array(),
+      exchanges: z.unknown().array(),
+      options: z.unknown().array(),
+      filling_rate: TYPE_UNDOCUMENTED_NULLABLE,
+      private_comment: TYPE_UNDOCUMENTED_NULLABLE,
+      interagency_comment: TYPE_UNDOCUMENTED_NULLABLE,
+      status_comment: TYPE_UNDOCUMENTED_NULLABLE,
+      logs: z.unknown().array(),
+      referrals: z.unknown().array(),
+      created_at: z.string().transform(Converters.toDate),
+      updated_at: z.string().transform(Converters.toDate),
+      created_by: z.coerce.number(),
+      updated_by: z.coerce.number(),
+    },
+  )
+}

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

@@ -0,0 +1,110 @@
+import type { CatalogName } from '../../consts/catalogs'
+import type { ApiCulture } from '../../consts/languages'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { DummyCache } from './dummy.cache'
+import { CacheExpiredError } from './types'
+
+describe('cache - Dummy', () => {
+  let cache: DummyCache
+
+  beforeEach(() => {
+    cache = new DummyCache()
+  })
+
+  afterEach(() => {
+    // No cleanup needed for dummy cache
+  })
+
+  describe('constructor', () => {
+    it('should create an instance without any configuration', () => {
+      const dummyCache = new DummyCache()
+      expect(dummyCache).toBeInstanceOf(DummyCache)
+    })
+  })
+
+  describe('setEntries', () => {
+    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 not throw when setting entries', async () => {
+      const catalogName: CatalogName = 'book_step'
+      await expect(cache.setEntries(catalogName, culture, entries)).resolves.toBeUndefined()
+    })
+
+    it('should handle empty entries array', async () => {
+      const catalogName: CatalogName = 'book_step'
+      await expect(cache.setEntries(catalogName, culture, [])).resolves.toBeUndefined()
+    })
+
+    it('should handle different catalog and culture combinations', async () => {
+      await expect(cache.setEntries('book_step', 'en', entries)).resolves.toBeUndefined()
+      await expect(cache.setEntries('property_land', 'fr', entries)).resolves.toBeUndefined()
+      await expect(cache.setEntries('property_type', 'de', entries)).resolves.toBeUndefined()
+    })
+  })
+
+  describe('getEntry', () => {
+    const culture: ApiCulture = 'en'
+
+    it('should always throw CacheExpiredError regardless of parameters', async () => {
+      const catalogName: CatalogName = 'book_step'
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow(CacheExpiredError)
+    })
+
+    it('should throw CacheExpiredError for any ID', async () => {
+      const catalogName: CatalogName = 'book_step'
+      await expect(cache.getEntry(catalogName, culture, 999)).rejects.toThrow(CacheExpiredError)
+      await expect(cache.getEntry(catalogName, culture, 0)).rejects.toThrow(CacheExpiredError)
+      await expect(cache.getEntry(catalogName, culture, -1)).rejects.toThrow(CacheExpiredError)
+    })
+
+    it('should throw CacheExpiredError for different catalogs and cultures', async () => {
+      await expect(cache.getEntry('book_step', 'en', 1)).rejects.toThrow(CacheExpiredError)
+      await expect(cache.getEntry('property_land', 'fr', 1)).rejects.toThrow(CacheExpiredError)
+      await expect(cache.getEntry('property_type', 'de', 1)).rejects.toThrow(CacheExpiredError)
+    })
+
+    it('should throw CacheExpiredError even after setting entries', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const entries = [{ id: 1, name: 'Item 1', name_plurial: 'Items 1' }]
+
+      await cache.setEntries(catalogName, culture, entries)
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow(CacheExpiredError)
+    })
+  })
+
+  describe('behavior consistency', () => {
+    it('should behave consistently across multiple calls', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const culture: ApiCulture = 'en'
+      const entries = [{ id: 1, name: 'Item 1', name_plurial: 'Items 1' }]
+
+      // Multiple setEntries calls should not throw
+      await expect(cache.setEntries(catalogName, culture, entries)).resolves.toBeUndefined()
+      await expect(cache.setEntries(catalogName, culture, entries)).resolves.toBeUndefined()
+
+      // Multiple getEntry calls should always throw
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow(CacheExpiredError)
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow(CacheExpiredError)
+    })
+
+    it('should maintain dummy behavior regardless of cache state', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const culture: ApiCulture = 'en'
+
+      // Should throw before any operations
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow(CacheExpiredError)
+
+      // Should still throw after setting entries
+      await cache.setEntries(catalogName, culture, [{ id: 1, name: 'Test', name_plurial: 'Tests' }])
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow(CacheExpiredError)
+
+      // Should still throw after multiple operations
+      await cache.setEntries(catalogName, culture, [])
+      await expect(cache.getEntry(catalogName, culture, 999)).rejects.toThrow(CacheExpiredError)
+    })
+  })
+})

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

@@ -0,0 +1,21 @@
+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'
+
+export class DummyCache implements ApiCacheAdapter {
+  constructor() {
+  }
+
+  async getEntries(_catalogName: CatalogName, _culture: ApiCulture): Promise<CatalogEntry[]> {
+    throw new CacheExpiredError()
+  }
+
+  async setEntries(_catalogName: CatalogName, _culture: ApiCulture, _entries: CatalogEntry[]): Promise<void> {
+  }
+
+  async getEntry(_catalogName: CatalogName, _culture: ApiCulture, _id: number): Promise<CatalogEntryName | null> {
+    throw new CacheExpiredError()
+  }
+}

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

@@ -0,0 +1,243 @@
+import type { CatalogName } from '../../consts/catalogs'
+import type { ApiCulture } from '../../consts/languages'
+import { existsSync, mkdirSync, rmSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { FilesystemCache } from './filesystem.cache'
+import { CacheExpiredError } from './types'
+
+describe('cache - Filesystem', () => {
+  let tempDir: string
+  let cache: FilesystemCache
+
+  beforeEach(() => {
+    // Create a unique temporary directory for each test
+    tempDir = path.join(os.tmpdir(), `filesystem-cache-test-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+    mkdirSync(tempDir, { recursive: true })
+  })
+
+  afterEach(() => {
+    // Clean up the temporary directory after each test
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+
+  describe('constructor', () => {
+    it('should use default cache location and expiration when no settings provided', () => {
+      // eslint-disable-next-line no-new
+      new FilesystemCache()
+      expect(existsSync('./cache/catalogs')).toBe(true)
+    })
+
+    it('should create custom cache directory when provided', () => {
+      const customPath = path.join(tempDir, 'custom-cache')
+      cache = new FilesystemCache({ path: customPath })
+      expect(existsSync(customPath)).toBe(true)
+    })
+
+    it('should use custom expiration time when provided', () => {
+      const customExpiration = 60000
+      cache = new FilesystemCache({
+        path: tempDir,
+        cacheExpirationMs: customExpiration,
+      })
+      // The expiration time is private, but we can test its effect
+      expect(cache).toBeInstanceOf(FilesystemCache)
+    })
+
+    it('should create nested directories recursively', () => {
+      const nestedPath = path.join(tempDir, 'level1', 'level2', 'cache')
+      cache = new FilesystemCache({ path: nestedPath })
+      expect(existsSync(nestedPath)).toBe(true)
+    })
+  })
+
+  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' },
+    ]
+
+    beforeEach(() => {
+      cache = new FilesystemCache({ path: tempDir })
+    })
+
+    it('should store and retrieve entries correctly', async () => {
+      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 create cache file with correct format', async () => {
+      const catalogName: CatalogName = 'book_step'
+      await cache.setEntries(catalogName, culture, entries)
+
+      const filePath = path.join(tempDir, `${catalogName}-${culture}.json`)
+      expect(existsSync(filePath)).toBe(true)
+
+      const fileContent = await readFile(filePath, 'utf-8')
+      const parsed = JSON.parse(fileContent)
+
+      expect(parsed).toHaveProperty('timestamp')
+      expect(parsed).toHaveProperty('cache')
+      expect(parsed.cache).toEqual({
+        1: { name: 'Item 1', namePlural: 'Items 1' },
+        2: { name: 'Item 2', namePlural: 'Items 2' },
+      })
+      expect(typeof parsed.timestamp).toBe('number')
+    })
+
+    it('should return null for non-existent entry', async () => {
+      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 file does not exist', async () => {
+      const catalogName: CatalogName = 'book_step'
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow(CacheExpiredError)
+    })
+
+    it('should throw CacheExpiredError when cache has expired', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const expiredCache = new FilesystemCache({
+        path: tempDir,
+        cacheExpirationMs: 1,
+      })
+      await expiredCache.setEntries(catalogName, culture, entries)
+
+      await new Promise(resolve => setTimeout(resolve, 10))
+
+      await expect(expiredCache.getEntry(catalogName, culture, 1)).rejects.toThrow(CacheExpiredError)
+    })
+
+    it('should handle different catalog and culture combinations', async () => {
+      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.toThrow(CacheExpiredError)
+
+      // Verify separate files were created
+      expect(existsSync(path.join(tempDir, 'book_step-en.json'))).toBe(true)
+      expect(existsSync(path.join(tempDir, 'property_land-fr.json'))).toBe(true)
+      expect(existsSync(path.join(tempDir, 'book_step-fr.json'))).toBe(false)
+    })
+
+    it('should overwrite existing cache when setting new entries', async () => {
+      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()
+    })
+
+    it('should handle entries with undefined name_plurial', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const entriesWithUndefined = [
+        { id: 1, name: 'Item 1', name_plurial: undefined },
+        { id: 2, name: 'Item 2', name_plurial: 'Items 2' },
+      ]
+
+      await cache.setEntries(catalogName, culture, entriesWithUndefined)
+
+      const entry1 = await cache.getEntry(catalogName, culture, 1)
+      const entry2 = await cache.getEntry(catalogName, culture, 2)
+
+      expect(entry1).toEqual({ name: 'Item 1', namePlural: undefined })
+      expect(entry2).toEqual({ name: 'Item 2', namePlural: 'Items 2' })
+    })
+
+    it('should handle large entry IDs correctly', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const largeIdEntries = [
+        { id: 999999999, name: 'Large ID Item', name_plurial: 'Large ID Items' },
+      ]
+
+      await cache.setEntries(catalogName, culture, largeIdEntries)
+
+      const entry = await cache.getEntry(catalogName, culture, 999999999)
+      expect(entry).toEqual({ name: 'Large ID Item', namePlural: 'Large ID Items' })
+    })
+
+    it('should persist cache across multiple FilesystemCache instances', async () => {
+      const catalogName: CatalogName = 'book_step'
+
+      // Create cache with first instance
+      const cache1 = new FilesystemCache({ path: tempDir })
+      await cache1.setEntries(catalogName, culture, entries)
+
+      // Access cache with second instance
+      const cache2 = new FilesystemCache({ path: tempDir })
+      const entry = await cache2.getEntry(catalogName, culture, 1)
+
+      expect(entry).toEqual({ name: 'Item 1', namePlural: 'Items 1' })
+    })
+  })
+
+  describe('error handling', () => {
+    beforeEach(() => {
+      cache = new FilesystemCache({ path: tempDir })
+    })
+
+    it('should handle malformed JSON files gracefully', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const culture: ApiCulture = 'en'
+      const filePath = path.join(tempDir, `${catalogName}-${culture}.json`)
+
+      // Write malformed JSON
+      await writeFile(filePath, 'invalid json content')
+
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow()
+    })
+
+    it('should handle files with missing timestamp', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const culture: ApiCulture = 'en'
+      const filePath = path.join(tempDir, `${catalogName}-${culture}.json`)
+
+      // Write JSON without timestamp
+      await writeFile(filePath, JSON.stringify({
+        cache: { 1: { name: 'Test', namePlural: 'Tests' } },
+      }))
+
+      await expect(cache.getEntry(catalogName, culture, 1)).resolves.toStrictEqual({ name: 'Test', namePlural: 'Tests' })
+    })
+
+    it('should handle files with missing cache property', async () => {
+      const catalogName: CatalogName = 'book_step'
+      const culture: ApiCulture = 'en'
+      const filePath = path.join(tempDir, `${catalogName}-${culture}.json`)
+
+      // Write JSON without cache property
+      await writeFile(filePath, JSON.stringify({
+        timestamp: Date.now(),
+      }))
+
+      await expect(cache.getEntry(catalogName, culture, 1)).rejects.toThrow()
+    })
+  })
+})