@digelo/cobid

Minimal in-memory auction server using WebSockets and @digelo/signal for events.

Architecture

Think of it as three small parts working together: the HTTP server speaks REST and WebSocket, the in-memory store keeps the auction state and validates bids, and Signal acts like the internal announcer that broadcasts new bids and items to every connected client.

Install

npm install @digelo/cobid

Run

npm run start

The server listens on http://localhost:3000 by default.

Frontend (optional)

The frontend lives in this GitHub repo under public/, but it is excluded from the npm package. To serve it locally from the repo:

SERVE_FRONTEND=true npm run start

REST API

• GET /api/auctions - list items and highest bids
• POST /api/auctions - create a new auction item

WebSocket

Send bids:

{ "type": "bid", "itemId": "...", "amount": 125, "bidder": "Alex" }

Receive updates:

{ "type": "highestBid", "itemId": "...", "highestBid": 125 }

{ "type": "newItem", "item": { "id": "...", "title": "..." } }

Publish checklist

• Update version in package.json
• Run npm pack and inspect the tarball contents
• Run npm publish --access public

Making bids persistent

You can replace the in-memory store with a database-backed implementation without changing the rest of the app. The server only depends on the store methods below.

1) Keep the same store interface

AuctionStore exposes three methods that the server calls:

• list()
• createItem({ title, startingBid })
• placeBid({ itemId, amount, bidder })

Create a new file (for example, src/persistentStore.js) that implements the same method signatures, but uses your database instead of a Map.

2) Use a transactional or atomic bid update

To prevent race conditions, make bid updates atomic in the database. The logic is:

• Load the item by ID
• Reject if the new bid is not higher
• Update the highest bid and bidder

In SQL, prefer a single conditional update (or a transaction) so two users cannot both win with the same previous price.

3) Swap the store in the server

Update the import in src/server.js to use your new store:

import { PersistentStore } from "./persistentStore.js";
const store = new PersistentStore();

4) Remove seeding and load from DB

Instead of calling store.createItem(...) at startup, load initial items from the database or start with an empty table/collection.

5) Keep Signal events as-is

The Signal calls (emitHighestBid, emitNewItem) can stay the same. Just emit after the database write succeeds.

If you want a concrete adapter for a specific database (SQLite, Postgres, MongoDB), tell me which one and I can sketch it out.