@shipload/sdk 1.0.0-next.6 → 1.0.0-next.60

package/src/subscriptions/manager.ts

@@ -3,6 +3,9 @@ import type {
     BoundingBox,
     BoundsDeltaMessage,
     ClientMessage,
+    ClusterCellWire,
+    ClusterDeltaMessage,
+    EntityDeletedMessage,
     ServerMessage,
     SnapshotMessage,
     SubscribeEntityMessage,
@@ -13,12 +16,10 @@ import type {
     WireEntity,
 } from './types'
 import {mapEntity, parseWireEntity} from './mappers'
-import type {Ship} from '../entities/ship'
-import type {Warehouse} from '../entities/warehouse'
-import type {Container} from '../entities/container'
+import type {Entity} from '../entities/entity'
 
-export type SubscriptionEntityType = 'ship' | 'warehouse' | 'container'
-export type EntityInstance = Ship | Warehouse | Container
+export type SubscriptionEntityType = 'ship' | 'warehouse' | 'container' | 'nexus'
+export type EntityInstance = Entity
 
 export interface SubscriptionsOptions {
     url: string
@@ -27,50 +28,79 @@ export interface SubscriptionsOptions {
     pongTimeoutMs?: number
 }
 
-export interface BoundsSubscriptionHandle {
-    readonly subId: string
-    unsubscribe(): void
-    updateBounds(bounds: BoundingBox): void
-    current: Map<number, EntityInstance>
+export type ExactEntitySubscriptionFilter = {
+    id: string | number
+    owner?: never
+    bounds?: never
+    prioritizeOwner?: never
 }
 
-export interface OwnerSubscriptionHandle {
+export type BroadEntitySubscriptionFilter = {
+    id?: undefined
+    owner?: string
+    bounds?: BoundingBox
+    prioritizeOwner?: string
+}
+
+export type EntitySubscriptionFilter = ExactEntitySubscriptionFilter | BroadEntitySubscriptionFilter
+
+export interface EntitySubscriptionMeta {
+    seq?: number
+    truncated?: boolean
+}
+
+export interface EntitySubscriptionHandlers {
+    onSnapshot?: (entities: EntityInstance[], meta: EntitySubscriptionMeta) => void
+    onUpdate?: (entity: EntityInstance, meta: EntitySubscriptionMeta) => void
+    onBoundsDelta?: (
+        entered: EntityInstance[],
+        exited: number[],
+        meta: EntitySubscriptionMeta
+    ) => void
+    onDeleted?: (id: string, meta: EntitySubscriptionMeta) => void
+    onError?: (error: Error) => void
+    onCluster?: (payload: {
+        hubId: number
+        seq: number
+        cells: ClusterCellWire[] | null
+        erased: boolean
+    }) => void
+}
+
+export interface EntitiesSubscriptionHandle {
     readonly subId: string
+    readonly filter: EntitySubscriptionFilter
     unsubscribe(): void
     current: Map<number, EntityInstance>
 }
 
-export interface EntitySubscriptionHandle {
-    readonly subId: string
-    readonly entityType: SubscriptionEntityType
-    readonly entityId: string
-    unsubscribe(): void
-    current: EntityInstance | null
+export type BoundsSubscriptionHandle = EntitiesSubscriptionHandle & {
+    readonly filter: BroadEntitySubscriptionFilter & {bounds: BoundingBox}
+    updateBounds(bounds: BoundingBox): void
+}
+export type OwnerSubscriptionHandle = EntitiesSubscriptionHandle & {
+    readonly filter: BroadEntitySubscriptionFilter
+}
+export type EntitySubscriptionHandle = EntitiesSubscriptionHandle & {
+    readonly filter: ExactEntitySubscriptionFilter
+}
+
+type EntitiesSubscriptionEntry = {
+    filter: InternalEntitySubscriptionFilter
+    handlers: EntitySubscriptionHandlers
+    handle: EntitiesSubscriptionHandle
+}
+
+type InternalEntitySubscriptionFilter = {
+    id?: string | number
+    owner?: string
+    bounds?: BoundingBox
+    prioritizeOwner?: string
 }
 
 export class SubscriptionsManager {
     private readonly conn: WebSocketConnection
-    private readonly entitySubs = new Map<
-        string,
-        {
-            type: SubscriptionEntityType
-            id: string
-            onUpdate: (e: EntityInstance) => void
-            handle: EntitySubscriptionHandle
-        }
-    >()
-    private readonly boundsSubs = new Map<
-        string,
-        {
-            bounds?: BoundingBox
-            owner?: string
-            prioritizeOwner?: string
-            onSnapshot?: (entities: EntityInstance[]) => void
-            onUpdate?: (entity: EntityInstance) => void
-            onBoundsDelta?: (entered: EntityInstance[], exited: number[]) => void
-            handle: BoundsSubscriptionHandle | OwnerSubscriptionHandle
-        }
-    >()
+    private readonly entitySubs = new Map<string, EntitiesSubscriptionEntry>()
     private subCounter = 0
     private hasConnected = false
 
@@ -99,113 +129,162 @@ export class SubscriptionsManager {
         this.conn.send(msg)
     }
 
-    subscribeEntity(
-        type: SubscriptionEntityType,
-        id: string,
-        onUpdate: (e: EntityInstance) => void
-    ): EntitySubscriptionHandle {
-        const subId = this.generateSubID('ent')
-        const msg: SubscribeEntityMessage = {
-            type: 'subscribe_entity',
-            sub_id: subId,
-            entity_type: type,
-            entity_id: id,
-        }
-        const handle: EntitySubscriptionHandle = {
+    subscribeEntities(
+        filter: BroadEntitySubscriptionFilter & {bounds: BoundingBox},
+        handlers?: EntitySubscriptionHandlers
+    ): BoundsSubscriptionHandle
+    subscribeEntities(
+        filter: ExactEntitySubscriptionFilter,
+        handlers?: EntitySubscriptionHandlers
+    ): EntitySubscriptionHandle
+    subscribeEntities(
+        filter: BroadEntitySubscriptionFilter,
+        handlers?: EntitySubscriptionHandlers
+    ): EntitiesSubscriptionHandle
+    subscribeEntities(
+        filter: EntitySubscriptionFilter,
+        handlers?: EntitySubscriptionHandlers
+    ): EntitiesSubscriptionHandle
+    subscribeEntities(
+        filter: EntitySubscriptionFilter,
+        handlers: EntitySubscriptionHandlers = {}
+    ): EntitiesSubscriptionHandle {
+        const storedFilter = this.normalizeFilter(filter)
+        const subId = this.generateSubID(this.subscriptionPrefix(storedFilter))
+        const handle: EntitiesSubscriptionHandle = {
             subId,
-            entityType: type,
-            entityId: id,
-            unsubscribe: () => this.unsubscribeEntity(subId),
-            current: null,
+            get filter() {
+                return SubscriptionsManager.publicFilter(storedFilter)
+            },
+            unsubscribe: () => this.unsubscribeEntities(subId),
+            current: new Map(),
         }
-        this.entitySubs.set(subId, {type, id, onUpdate, handle})
-        this.sendMessage(msg)
+        if (storedFilter.id === undefined && storedFilter.bounds) {
+            ;(handle as BoundsSubscriptionHandle).updateBounds = (bounds) =>
+                this.updateBounds(subId, bounds)
+        }
+
+        this.entitySubs.set(subId, {filter: storedFilter, handlers, handle})
+        this.sendMessage(this.subscribeMessage(subId, storedFilter))
         return handle
     }
 
-    private unsubscribeEntity(subId: string) {
-        const entry = this.entitySubs.get(subId)
-        if (!entry) return
-        this.entitySubs.delete(subId)
-        const msg: UnsubscribeEntityMessage = {type: 'unsubscribe_entity', sub_id: subId}
-        this.sendMessage(msg)
+    subscribeEntity(
+        id: string | number,
+        handlers: EntitySubscriptionHandlers
+    ): EntitySubscriptionHandle {
+        return this.subscribeEntities({id}, handlers)
+    }
+
+    subscribeOwner(
+        owner: string,
+        handlers: EntitySubscriptionHandlers = {}
+    ): OwnerSubscriptionHandle {
+        return this.subscribeEntities({owner}, handlers) as OwnerSubscriptionHandle
     }
 
     subscribeBounds(
         bounds: BoundingBox,
-        handlers: {
-            onSnapshot?: (entities: EntityInstance[]) => void
-            onUpdate?: (entity: EntityInstance) => void
-            onBoundsDelta?: (entered: EntityInstance[], exited: number[]) => void
+        handlers: EntitySubscriptionHandlers & {
             owner?: string
             prioritizeOwner?: string
-        }
+        } = {}
     ): BoundsSubscriptionHandle {
-        const subId = this.generateSubID('bnd')
-        const msg: SubscribeMessage = {
-            type: 'subscribe',
-            sub_id: subId,
-            bounds,
-            owner: handlers.owner,
-            prioritize_owner: handlers.prioritizeOwner,
+        return this.subscribeEntities(
+            {bounds, owner: handlers.owner, prioritizeOwner: handlers.prioritizeOwner},
+            handlers
+        )
+    }
+
+    subscribeAllEntities(handlers: EntitySubscriptionHandlers = {}): EntitiesSubscriptionHandle {
+        return this.subscribeEntities({}, handlers)
+    }
+
+    private normalizeFilter(filter: EntitySubscriptionFilter): InternalEntitySubscriptionFilter {
+        const raw = filter as InternalEntitySubscriptionFilter
+        if (
+            raw.id !== undefined &&
+            (raw.owner !== undefined ||
+                raw.bounds !== undefined ||
+                raw.prioritizeOwner !== undefined)
+        ) {
+            throw new Error(
+                'Exact entity subscription filters cannot include owner, bounds, or prioritizeOwner'
+            )
         }
-        const handle: BoundsSubscriptionHandle = {
-            subId,
-            unsubscribe: () => this.unsubscribeBounds(subId),
-            updateBounds: (b) => this.updateBounds(subId, b),
-            current: new Map(),
+        if (raw.id !== undefined) {
+            return {id: raw.id}
+        }
+        return {
+            owner: raw.owner,
+            bounds: raw.bounds ? this.cloneBounds(raw.bounds) : undefined,
+            prioritizeOwner: raw.prioritizeOwner,
         }
-        this.boundsSubs.set(subId, {
-            bounds,
-            owner: handlers.owner,
-            prioritizeOwner: handlers.prioritizeOwner,
-            onSnapshot: handlers.onSnapshot,
-            onUpdate: handlers.onUpdate,
-            onBoundsDelta: handlers.onBoundsDelta,
-            handle,
-        })
-        this.sendMessage(msg)
-        return handle
     }
 
-    subscribeOwner(
-        owner: string,
-        handlers: {
-            onSnapshot?: (entities: EntityInstance[]) => void
-            onUpdate?: (entity: EntityInstance) => void
-        } = {}
-    ): OwnerSubscriptionHandle {
-        const subId = this.generateSubID('own')
-        const msg: SubscribeMessage = {
+    private static publicFilter(
+        filter: InternalEntitySubscriptionFilter
+    ): EntitySubscriptionFilter {
+        if (filter.id !== undefined) {
+            return Object.freeze({id: filter.id}) as ExactEntitySubscriptionFilter
+        }
+
+        return Object.freeze({
+            owner: filter.owner,
+            bounds: filter.bounds ? (Object.freeze({...filter.bounds}) as BoundingBox) : undefined,
+            prioritizeOwner: filter.prioritizeOwner,
+        }) as BroadEntitySubscriptionFilter
+    }
+
+    private cloneBounds(bounds: BoundingBox): BoundingBox {
+        return {...bounds}
+    }
+
+    private subscriptionPrefix(filter: InternalEntitySubscriptionFilter): string {
+        if (filter.id !== undefined) return 'ent'
+        if (filter.bounds) return 'bnd'
+        if (filter.owner) return 'own'
+        return 'all'
+    }
+
+    private subscribeMessage(
+        subId: string,
+        filter: InternalEntitySubscriptionFilter
+    ): SubscribeEntityMessage | SubscribeMessage {
+        if (filter.id !== undefined) {
+            return {
+                type: 'subscribe_entity',
+                sub_id: subId,
+                entity_id: String(filter.id),
+            }
+        }
+
+        return {
             type: 'subscribe',
             sub_id: subId,
-            owner,
+            owner: filter.owner,
+            bounds: filter.bounds,
+            prioritize_owner: filter.prioritizeOwner,
         }
-        const handle: OwnerSubscriptionHandle = {
-            subId,
-            unsubscribe: () => this.unsubscribeBounds(subId),
-            current: new Map(),
-        }
-        this.boundsSubs.set(subId, {
-            bounds: undefined,
-            owner,
-            prioritizeOwner: undefined,
-            onSnapshot: handlers.onSnapshot,
-            onUpdate: handlers.onUpdate,
-            handle,
-        })
-        this.sendMessage(msg)
-        return handle
     }
 
-    private unsubscribeBounds(subId: string) {
-        this.boundsSubs.delete(subId)
+    private unsubscribeEntities(subId: string) {
+        const entry = this.entitySubs.get(subId)
+        if (!entry) return
+        this.entitySubs.delete(subId)
+        if (entry.filter.id !== undefined) {
+            const msg: UnsubscribeEntityMessage = {type: 'unsubscribe_entity', sub_id: subId}
+            this.sendMessage(msg)
+            return
+        }
         this.sendMessage({type: 'unsubscribe', sub_id: subId})
     }
 
     private updateBounds(subId: string, bounds: BoundingBox) {
-        const entry = this.boundsSubs.get(subId)
-        if (entry) entry.bounds = bounds
+        const entry = this.entitySubs.get(subId)
+        if (!entry) return
+        if (entry.filter.id !== undefined || !entry.filter.bounds) return
+        entry.filter.bounds = this.cloneBounds(bounds)
         const msg: UpdateBoundsMessage = {type: 'update_bounds', sub_id: subId, bounds}
         this.sendMessage(msg)
     }
@@ -217,23 +296,7 @@ export class SubscriptionsManager {
             return
         }
         for (const [subId, entry] of this.entitySubs) {
-            const msg: SubscribeEntityMessage = {
-                type: 'subscribe_entity',
-                sub_id: subId,
-                entity_type: entry.type,
-                entity_id: entry.id,
-            }
-            this.sendMessage(msg)
-        }
-        for (const [subId, entry] of this.boundsSubs) {
-            const msg: SubscribeMessage = {
-                type: 'subscribe',
-                sub_id: subId,
-                bounds: entry.bounds,
-                owner: entry.owner,
-                prioritize_owner: entry.prioritizeOwner,
-            }
-            this.sendMessage(msg)
+            this.sendMessage(this.subscribeMessage(subId, entry.filter))
         }
     }
 
@@ -248,6 +311,12 @@ export class SubscriptionsManager {
             case 'bounds_delta':
                 this.handleBoundsDelta(msg)
                 break
+            case 'entity_deleted':
+                this.handleEntityDeleted(msg)
+                break
+            case 'cluster':
+                this.handleCluster(msg)
+                break
             case 'error':
                 this.handleError(msg)
                 break
@@ -260,60 +329,64 @@ export class SubscriptionsManager {
     }
 
     private handleSnapshot(msg: SnapshotMessage) {
-        const entSub = this.entitySubs.get(msg.sub_id)
-        if (entSub) {
-            if (msg.entities.length > 0) {
-                const ent = this.parseEntity(msg.entities[0])
-                entSub.handle.current = ent
-                entSub.onUpdate(ent)
-            }
-            return
-        }
-        const boundsSub = this.boundsSubs.get(msg.sub_id)
-        if (boundsSub) {
-            const ents = msg.entities.map((e) => this.parseEntity(e))
-            boundsSub.handle.current.clear()
-            for (const e of ents) boundsSub.handle.current.set(Number(e.id), e)
-            boundsSub.onSnapshot?.(ents)
+        const sub = this.entitySubs.get(msg.sub_id)
+        if (!sub) return
+        const meta = {seq: msg.seq, truncated: msg.truncated === true}
+        const ents = msg.entities.map((e) => this.parseEntity(e))
+        sub.handle.current.clear()
+        for (const e of ents) sub.handle.current.set(Number(e.id), e)
+        sub.handlers.onSnapshot?.(ents, meta)
+        if (sub.filter.id !== undefined && ents[0]) {
+            sub.handlers.onUpdate?.(ents[0], {seq: msg.seq})
         }
     }
 
     private handleUpdate(msg: UpdateMessage) {
         const ent = this.parseEntity(msg.entity)
         for (const subId of msg.sub_ids) {
-            const entSub = this.entitySubs.get(subId)
-            if (entSub) {
-                entSub.handle.current = ent
-                entSub.onUpdate(ent)
-                continue
-            }
-            const boundsSub = this.boundsSubs.get(subId)
-            if (boundsSub) {
-                boundsSub.handle.current.set(msg.entity_id, ent)
-                boundsSub.onUpdate?.(ent)
-            }
+            const sub = this.entitySubs.get(subId)
+            if (!sub) continue
+            sub.handle.current.set(msg.entity_id, ent)
+            sub.handlers.onUpdate?.(ent, {seq: msg.seq})
         }
     }
 
     private handleBoundsDelta(msg: BoundsDeltaMessage) {
-        const sub = this.boundsSubs.get(msg.sub_id)
+        const sub = this.entitySubs.get(msg.sub_id)
         if (!sub) return
+        const meta = {seq: msg.seq, truncated: msg.truncated === true}
         const entered = msg.entered.map((e) => this.parseEntity(e))
         for (const e of entered) sub.handle.current.set(Number(e.id), e)
         for (const id of msg.exited) sub.handle.current.delete(id)
-        sub.onBoundsDelta?.(entered, msg.exited)
+        sub.handlers.onBoundsDelta?.(entered, msg.exited, meta)
     }
 
     private handleError(msg: {sub_id?: string; error: string}) {
         if (!msg.sub_id) return
-        const entSub = this.entitySubs.get(msg.sub_id)
-        if (entSub) {
+        const sub = this.entitySubs.get(msg.sub_id)
+        if (!sub) return
+        this.entitySubs.delete(msg.sub_id)
+        sub.handlers.onError?.(new Error(msg.error))
+    }
+
+    private handleEntityDeleted(msg: EntityDeletedMessage) {
+        const sub = this.entitySubs.get(msg.sub_id)
+        if (!sub) return
+        sub.handle.current.delete(msg.entity_id)
+        if (sub.filter.id !== undefined) {
             this.entitySubs.delete(msg.sub_id)
-            return
-        }
-        const boundsSub = this.boundsSubs.get(msg.sub_id)
-        if (boundsSub) {
-            this.boundsSubs.delete(msg.sub_id)
         }
+        sub.handlers.onDeleted?.(String(msg.entity_id), {seq: msg.seq})
+    }
+
+    private handleCluster(msg: ClusterDeltaMessage) {
+        const sub = this.entitySubs.get(msg.sub_id)
+        if (!sub) return
+        sub.handlers.onCluster?.({
+            hubId: msg.hub_id,
+            seq: msg.seq,
+            cells: msg.erased ? null : (msg.cells ?? []),
+            erased: msg.erased === true,
+        })
     }
 }

package/src/subscriptions/mappers.ts

@@ -1,14 +1,9 @@
 import {ServerContract} from '../contracts'
-import {Ship} from '../entities/ship'
-import {Warehouse} from '../entities/warehouse'
-import {Container} from '../entities/container'
+import {Entity} from '../entities/entity'
 import type {WireEntity} from './types'
 
-export function mapEntity(ei: ServerContract.Types.entity_info): Ship | Warehouse | Container {
-    if (ei.type.equals('ship')) return new Ship(ei)
-    if (ei.type.equals('warehouse')) return new Warehouse(ei)
-    if (ei.type.equals('container')) return new Container(ei)
-    throw new Error(`mapEntity: unknown entity type ${ei.type.toString()}`)
+export function mapEntity(ei: ServerContract.Types.entity_info): Entity {
+    return new Entity(ei)
 }
 
 export function parseWireEntity(raw: WireEntity): ServerContract.Types.entity_info {
@@ -24,5 +19,7 @@ export function parseWireEntity(raw: WireEntity): ServerContract.Types.entity_in
     }
     delete shaped.name
 
+    if (shaped.holds === undefined) shaped.holds = []
+
     return ServerContract.Types.entity_info.from(shaped)
 }

package/src/subscriptions/types.ts

@@ -39,7 +39,6 @@ export type UnsubscribeMessage = {
 export type SubscribeEntityMessage = {
     type: 'subscribe_entity'
     sub_id: string
-    entity_type: 'ship' | 'warehouse' | 'container'
     entity_id: string
 }
 
@@ -79,11 +78,12 @@ export type AckMessage = {
 }
 
 export type WireEntity = Record<string, unknown> & {
-    type: number
-    type_name: 'ship' | 'warehouse' | 'container'
+    type: number | string
+    type_name?: string
     id: string | number
     owner: string
     coordinates: WireCoordinates
+    item_id: number
 }
 
 export type SnapshotMessage = {
@@ -111,6 +111,13 @@ export type BoundsDeltaMessage = {
     truncated?: boolean
 }
 
+export type EntityDeletedMessage = {
+    type: 'entity_deleted'
+    sub_id: string
+    entity_id: number
+    seq: number
+}
+
 export type EventMessage = {
     type: 'event'
     sub_id: string
@@ -132,12 +139,30 @@ export type ErrorMessage = {
     sub_id?: string
 }
 
+export interface ClusterCellWire {
+    gx: number
+    gy: number
+    entity: number
+    type?: string
+}
+
+export type ClusterDeltaMessage = {
+    type: 'cluster'
+    sub_id: string
+    hub_id: number
+    seq: number
+    cells?: ClusterCellWire[]
+    erased?: boolean
+}
+
 export type ServerMessage =
     | AckMessage
     | SnapshotMessage
     | UpdateMessage
     | BoundsDeltaMessage
+    | EntityDeletedMessage
     | EventMessage
     | EventCatchupCompleteMessage
     | PongMessage
     | ErrorMessage
+    | ClusterDeltaMessage

package/src/testing/catalog-hash.ts

@@ -0,0 +1,19 @@
+import {createHash} from 'node:crypto'
+import {readFileSync} from 'node:fs'
+
+export const CATALOG_FILES_REL = [
+    'items.json',
+    'recipes.json',
+    'entities.json',
+    'kind-registry.json',
+    'item-ids.ts',
+] as const
+
+export function computeCatalogHash(filePaths: ReadonlyArray<string>): string {
+    const hash = createHash('sha256')
+    for (const p of filePaths) {
+        hash.update(readFileSync(p))
+        hash.update('\0')
+    }
+    return hash.digest('hex')
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export * from './catalog-hash'
+export * from './projection-parity'