screeps-connectivity 0.2.0

package/tests/stores/RoomStore.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi } from 'vitest'
+import { RoomStore } from '../../src/stores/RoomStore.js'
+import { Cache } from '../../src/cache/Cache.js'
+import { TerrainType } from '../../src/types/game.js'
+
+function makeStore() {
+  const http = {
+    game: {
+      roomTerrain: vi.fn().mockResolvedValue({
+        ok: 1,
+        terrain: [{ _id: 'id', room: 'W7N7', terrain: '0'.repeat(2500), type: 'terrain' }],
+      }),
+      roomObjects: vi.fn().mockResolvedValue({ ok: 1, objects: [], users: {} }),
+    },
+  } as unknown as import('../../src/http/HttpClient.js').HttpClient
+
+  const socket = {
+    subscribe: vi.fn().mockReturnValue({ dispose: vi.fn() }),
+    on: vi.fn().mockReturnValue({ dispose: vi.fn() }),
+  } as unknown as import('../../src/socket/SocketClient.js').SocketClient
+
+  const cache = new Cache('test', null)
+  const store = new RoomStore(http, socket, cache)
+  return { store, http, socket, cache }
+}
+
+describe('RoomStore', () => {
+  it('fetches terrain from API on first call', async () => {
+    const { store, http } = makeStore()
+    const terrain = await store.terrain('W7N7', 'shard0')
+    expect(http.game.roomTerrain).toHaveBeenCalledWith('W7N7', 'shard0')
+    expect(terrain.get(0, 0)).toBe(TerrainType.Plain)
+  })
+
+  it('returns cached terrain on second call', async () => {
+    const { store, http } = makeStore()
+    await store.terrain('W7N7', 'shard0')
+    await store.terrain('W7N7', 'shard0')
+    expect(http.game.roomTerrain).toHaveBeenCalledOnce()
+  })
+
+  it('objects() returns null before any subscription updates', () => {
+    const { store } = makeStore()
+    expect(store.objects('W7N7', 'shard0')).toBeNull()
+  })
+
+  it('subscribe() calls socket.subscribe with the correct channel', () => {
+    const { store, socket } = makeStore()
+    store.subscribe('W7N7', 'shard0')
+    expect(socket.subscribe).toHaveBeenCalledWith('room:shard0/W7N7')
+  })
+
+  it('subscribe() omits shard prefix when shard is null (private server)', () => {
+    const { store, socket } = makeStore()
+    store.subscribe('E9N3', null)
+    expect(socket.subscribe).toHaveBeenCalledWith('room:E9N3')
+  })
+
+  it('subscribe() returns a Subscription with dispose()', () => {
+    const { store } = makeStore()
+    const sub = store.subscribe('W7N7', 'shard0')
+    expect(typeof sub.dispose).toBe('function')
+  })
+
+  it('merges room object diff on WS updates', async () => {
+    const { store, socket } = makeStore()
+    let messageHandler: (data: unknown) => void = () => {}
+    ;(socket.on as ReturnType<typeof vi.fn>).mockImplementation((_ch: string, cb: (data: unknown) => void) => {
+      messageHandler = cb
+      return { dispose: vi.fn() }
+    })
+
+    store.subscribe('W7N7', 'shard0')
+
+    // First message: full state
+    messageHandler({
+      objects: { id1: { _id: 'id1', type: 'creep', room: 'W7N7', x: 10, y: 10 } },
+      gameTime: 1000,
+    })
+
+    expect(store.objects('W7N7', 'shard0')).toMatchObject({
+      id1: { _id: 'id1', type: 'creep' },
+    })
+
+    // Second message: diff
+    messageHandler({
+      objects: { id1: { x: 11, y: 11 } },
+      gameTime: 1001,
+    })
+
+    expect(store.objects('W7N7', 'shard0')?.['id1']).toMatchObject({ x: 11, y: 11, type: 'creep' })
+  })
+
+  it('emits room:update event on WS message', async () => {
+    const { store, socket } = makeStore()
+    let messageHandler: (data: unknown) => void = () => {}
+    ;(socket.on as ReturnType<typeof vi.fn>).mockImplementation((_ch: string, cb: (data: unknown) => void) => {
+      messageHandler = cb
+      return { dispose: vi.fn() }
+    })
+
+    const handler = vi.fn()
+    store.on('room:update', handler)
+    store.subscribe('W7N7', 'shard0')
+    messageHandler({ objects: {}, gameTime: 2000 })
+
+    expect(handler).toHaveBeenCalledWith(expect.objectContaining({ room: 'W7N7', shard: 'shard0', gameTime: 2000 }))
+  })
+
+  it('fetchObjects loads objects via HTTP and emits room:update', async () => {
+    const { store, http } = makeStore()
+    const mockObjects = [
+      { _id: 'o1', type: 'controller', room: 'E9N3', x: 25, y: 25 },
+      { _id: 'o2', type: 'source', room: 'E9N3', x: 10, y: 10 },
+    ]
+    ;(http.game as unknown as { roomObjects: ReturnType<typeof vi.fn> }).roomObjects = vi.fn().mockResolvedValue({ ok: 1, objects: mockObjects, users: {} })
+
+    const eventSpy = vi.fn()
+    store.on('room:update', eventSpy)
+
+    await store.fetchObjects('E9N3', 'shard0')
+
+    expect(http.game.roomObjects).toHaveBeenCalledWith('E9N3', 'shard0')
+    expect(eventSpy).toHaveBeenCalledOnce()
+    const update = eventSpy.mock.calls[0][0] as { objects: Record<string, unknown> }
+    expect(update.objects).toHaveProperty('o1')
+    expect(update.objects).toHaveProperty('o2')
+    expect(update.objects.o1).toEqual(expect.objectContaining({ type: 'controller' }))
+  })
+})

package/tests/stores/ServerStore.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi } from 'vitest'
+import { ServerStore } from '../../src/stores/ServerStore.js'
+import { Cache } from '../../src/cache/Cache.js'
+import type { ApiVersionResponse } from '../../src/types/api.js'
+
+const mockVersion: ApiVersionResponse = { ok: 1, package: 5, protocol: 13, users: 100, serverData: { historyChunkSize: 20, features: [], shards: ['shard0'] } }
+
+function makeStore() {
+  const http = {
+    request: vi.fn().mockResolvedValue({ ...mockVersion }),
+  } as unknown as import('../../src/http/HttpClient.js').HttpClient
+
+  const socket = {
+    on: vi.fn().mockReturnValue({ dispose: vi.fn() }),
+  } as unknown as import('../../src/socket/SocketClient.js').SocketClient
+
+  return { store: new ServerStore(http, socket, new Cache('test', null)), http, socket }
+}
+
+describe('ServerStore', () => {
+  it('fetches server version', async () => {
+    const { store } = makeStore()
+    const v = await store.version()
+    expect(v.protocol).toBe(13)
+  })
+
+  it('caches version after first fetch', async () => {
+    const { store, http } = makeStore()
+    await store.version()
+    await store.version()
+    expect(http.request).toHaveBeenCalledOnce()
+  })
+
+  it('emits server:connected when socket fires connected event', () => {
+    const { socket } = makeStore()
+    let connectedCb: (data: unknown) => void = () => {}
+    ;(socket.on as ReturnType<typeof vi.fn>).mockImplementation((ch: string, cb: (data: unknown) => void) => {
+      if (ch === 'connected') connectedCb = cb
+      return { dispose: vi.fn() }
+    })
+    // Re-create store to trigger the socket.on wiring
+    const store2 = new ServerStore(socket as unknown as import('../../src/http/HttpClient.js').HttpClient, socket, new Cache('t', null))
+    const spy = vi.fn()
+    store2.on('server:connected', spy)
+    connectedCb({})
+    expect(spy).toHaveBeenCalled()
+  })
+})

package/tests/stores/TypedStore.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, vi } from 'vitest'
+import { TypedStore } from '../../src/stores/TypedStore.js'
+
+interface TestEvents {
+  'test:event': { value: number }
+  'test:other': { name: string }
+}
+
+describe('TypedStore', () => {
+  it('delivers typed event detail to listener', () => {
+    const store = new TypedStore<TestEvents>()
+    const handler = vi.fn()
+    store.on('test:event', handler)
+    store.emit('test:event', { value: 42 })
+    expect(handler).toHaveBeenCalledWith({ value: 42 })
+  })
+
+  it('dispose() removes the listener', () => {
+    const store = new TypedStore<TestEvents>()
+    const handler = vi.fn()
+    const sub = store.on('test:event', handler)
+    sub.dispose()
+    store.emit('test:event', { value: 1 })
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it('multiple listeners on the same event all fire', () => {
+    const store = new TypedStore<TestEvents>()
+    const h1 = vi.fn()
+    const h2 = vi.fn()
+    store.on('test:event', h1)
+    store.on('test:event', h2)
+    store.emit('test:event', { value: 7 })
+    expect(h1).toHaveBeenCalledOnce()
+    expect(h2).toHaveBeenCalledOnce()
+  })
+
+  it('listeners on different events do not cross-fire', () => {
+    const store = new TypedStore<TestEvents>()
+    const h1 = vi.fn()
+    const h2 = vi.fn()
+    store.on('test:event', h1)
+    store.on('test:other', h2)
+    store.emit('test:event', { value: 1 })
+    expect(h1).toHaveBeenCalledOnce()
+    expect(h2).not.toHaveBeenCalled()
+  })
+
+  it('on() returns a Subscription compatible with SubscriptionGroup', () => {
+    const store = new TypedStore<TestEvents>()
+    const sub = store.on('test:event', vi.fn())
+    expect(typeof sub.dispose).toBe('function')
+  })
+})

package/tests/stores/UserStore.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from 'vitest'
+import { UserStore } from '../../src/stores/UserStore.js'
+import { Cache } from '../../src/cache/Cache.js'
+import type { UserInfo } from '../../src/types/game.js'
+
+const mockUser: UserInfo = { _id: 'uid1', username: 'user', email: 'a@b.com', cpu: 20, gcl: 100, credits: 50, badge: { type: 1, color1: '#fff', color2: '#000', color3: '#f00', param: 0, flip: false } }
+
+function makeStore() {
+  const http = {
+    auth: { me: vi.fn().mockResolvedValue({ ...mockUser, ok: 1 }) },
+    user: { worldStatus: vi.fn().mockResolvedValue({ ok: 1, status: 'normal' }) },
+  } as unknown as import('../../src/http/HttpClient.js').HttpClient
+
+  const socket = {
+    subscribe: vi.fn().mockReturnValue({ dispose: vi.fn() }),
+    on: vi.fn().mockReturnValue({ dispose: vi.fn() }),
+  } as unknown as import('../../src/socket/SocketClient.js').SocketClient
+
+  const cache = new Cache('test', null)
+  return { store: new UserStore(http, socket, cache), http, socket }
+}
+
+describe('UserStore', () => {
+  it('fetches user info from API', async () => {
+    const { store } = makeStore()
+    const user = await store.me()
+    expect(user.username).toBe('user')
+  })
+
+  it('fetches world status from API and emits event', async () => {
+    const { store, http } = makeStore()
+    const events: Array<{ status: string }> = []
+    store.on('user:worldStatus', e => events.push(e))
+
+    const status = await store.worldStatus()
+
+    expect(status).toBe('normal')
+    expect(store.worldStatusValue).toBe('normal')
+    expect(http.user.worldStatus).toHaveBeenCalledOnce()
+    expect(events).toEqual([{ status: 'normal' }])
+  })
+
+  it('caches world status after first fetch', async () => {
+    const { store, http } = makeStore()
+
+    await store.worldStatus()
+    await store.worldStatus()
+
+    expect(http.user.worldStatus).toHaveBeenCalledOnce()
+  })
+
+  it('refreshWorldStatus() bypasses cached world status', async () => {
+    const { store, http } = makeStore()
+
+    await store.worldStatus()
+    ;(http.user.worldStatus as unknown as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ ok: 1, status: 'lost' })
+    const status = await store.refreshWorldStatus()
+
+    expect(status).toBe('lost')
+    expect(http.user.worldStatus).toHaveBeenCalledTimes(2)
+  })
+
+  it('caches user info after first fetch', async () => {
+    const { store, http } = makeStore()
+    await store.me()
+    await store.me()
+    expect(http.auth.me).toHaveBeenCalledOnce()
+  })
+
+  it('deduplicates concurrent me() calls', async () => {
+    const { store, http } = makeStore()
+    let resolveMe: (value: unknown) => void = () => {}
+    ;(http.auth.me as unknown as ReturnType<typeof vi.fn>).mockImplementation(() => new Promise(r => { resolveMe = r }))
+
+    const p1 = store.me()
+    const p2 = store.me()
+    const p3 = store.me()
+
+    resolveMe({ ...mockUser, ok: 1 })
+
+    const [u1, u2, u3] = await Promise.all([p1, p2, p3])
+    expect(u1).toEqual(u2)
+    expect(u2).toEqual(u3)
+    expect(http.auth.me).toHaveBeenCalledOnce()
+  })
+
+  it('subscribe cpu starts WS subscription with userId prefix', async () => {
+    const { store, socket } = makeStore()
+    await store.me() // preload user id
+    store.subscribe('cpu')
+    await new Promise(r => setTimeout(r, 0)) // let async userId lookup settle
+    expect(socket.subscribe).toHaveBeenCalledWith('user:uid1/cpu')
+  })
+
+  it('cpu stats are updated via WS and event fired', async () => {
+    const { store, socket } = makeStore()
+    await store.me()
+    let handler: (data: unknown) => void = () => {}
+    ;(socket.on as ReturnType<typeof vi.fn>).mockImplementation((_ch: string, cb: (data: unknown) => void) => {
+      handler = cb
+      return { dispose: vi.fn() }
+    })
+    const eventSpy = vi.fn()
+    store.on('user:cpu', eventSpy)
+    store.subscribe('cpu')
+    await new Promise(r => setTimeout(r, 0))
+    handler({ cpu: 42, memory: 1024 })
+    expect(store.cpu).toEqual({ cpu: 42, memory: 1024 })
+    expect(eventSpy).toHaveBeenCalledWith({ cpu: 42, memory: 1024 })
+  })
+
+  it('console messages accumulate and emit event', async () => {
+    const { store, socket } = makeStore()
+    await store.me()
+    let handler: (data: unknown) => void = () => {}
+    ;(socket.on as ReturnType<typeof vi.fn>).mockImplementation((_ch: string, cb: (data: unknown) => void) => {
+      handler = cb
+      return { dispose: vi.fn() }
+    })
+    store.subscribe('console')
+    await new Promise(r => setTimeout(r, 0))
+    handler({ messages: { log: ['line1'], results: [] } })
+    expect(store.console).toHaveLength(1)
+  })
+
+  it('dispose() stops WS subscription', async () => {
+    const { store, socket } = makeStore()
+    await store.me()
+    const mockDispose = vi.fn()
+    ;(socket.subscribe as ReturnType<typeof vi.fn>).mockReturnValue({ dispose: mockDispose })
+    const sub = store.subscribe('cpu')
+    await new Promise(r => setTimeout(r, 0))
+    sub.dispose()
+    expect(mockDispose).toHaveBeenCalled()
+  })
+})

package/tests/subscription/SubscriptionGroup.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect, vi } from 'vitest'
+import { SubscriptionGroup } from '../../src/subscription/index.js'
+
+describe('SubscriptionGroup', () => {
+  it('calls dispose on all added subscriptions', () => {
+    const group = new SubscriptionGroup()
+    const d1 = vi.fn()
+    const d2 = vi.fn()
+    group.add({ dispose: d1 })
+    group.add({ dispose: d2 })
+    group.dispose()
+    expect(d1).toHaveBeenCalledOnce()
+    expect(d2).toHaveBeenCalledOnce()
+  })
+
+  it('clears internal list after dispose so second dispose is a no-op', () => {
+    const group = new SubscriptionGroup()
+    const d1 = vi.fn()
+    group.add({ dispose: d1 })
+    group.dispose()
+    group.dispose()
+    expect(d1).toHaveBeenCalledOnce()
+  })
+
+  it('itself satisfies the Subscription interface', () => {
+    const outer = new SubscriptionGroup()
+    const inner = new SubscriptionGroup()
+    const d = vi.fn()
+    inner.add({ dispose: d })
+    outer.add(inner)
+    outer.dispose()
+    expect(d).toHaveBeenCalledOnce()
+  })
+})

package/tests/types/game.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest'
+import { RoomTerrain, TerrainType } from '../../src/types/game.js'
+
+describe('RoomTerrain', () => {
+  it('parses plain, wall, swamp from encoded string', () => {
+    const encoded = '012' + '0'.repeat(2497)
+    const terrain = RoomTerrain.fromEncodedString(encoded)
+    expect(terrain.get(0, 0)).toBe(TerrainType.Plain)
+    expect(terrain.get(1, 0)).toBe(TerrainType.Wall)
+    expect(terrain.get(2, 0)).toBe(TerrainType.Swamp)
+  })
+
+  it('normalizes value 3 to Wall', () => {
+    const encoded = '3' + '0'.repeat(2499)
+    const terrain = RoomTerrain.fromEncodedString(encoded)
+    expect(terrain.get(0, 0)).toBe(TerrainType.Wall)
+  })
+
+  it('maps (x, y) to index y*50+x', () => {
+    // tile at x=0, y=1 is index 50
+    const chars = Array(2500).fill('0')
+    chars[50] = '1'
+    const terrain = RoomTerrain.fromEncodedString(chars.join(''))
+    expect(terrain.get(0, 1)).toBe(TerrainType.Wall)
+    expect(terrain.get(0, 0)).toBe(TerrainType.Plain)
+  })
+
+  it('exposes raw Uint8Array of length 2500', () => {
+    const terrain = RoomTerrain.fromEncodedString('0'.repeat(2500))
+    expect(terrain.raw).toBeInstanceOf(Uint8Array)
+    expect(terrain.raw.length).toBe(2500)
+  })
+
+  it('round-trips through raw bytes', () => {
+    const encoded = '012' + '0'.repeat(2497)
+    const terrain = RoomTerrain.fromEncodedString(encoded)
+    const restored = new RoomTerrain(terrain.raw)
+    expect(restored.get(0, 0)).toBe(TerrainType.Plain)
+    expect(restored.get(1, 0)).toBe(TerrainType.Wall)
+    expect(restored.get(2, 0)).toBe(TerrainType.Swamp)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "types": ["node"],
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/file-storage.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+})

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+  },
+})