tslib

TypeScript build-up libraries for Yingyeothon (잉여톤) hackathons, consolidated into a single monorepo. They are the server half of the yyt platform — a game runs as an actor in your own AWS account, talking to a realtime gateway you did not have to build — plus gamebase-client and kvstore-client, its browser half. The platform itself is specified in yingyeothon/service; the Unity client half is yingyeothon/csharplib. These packages started life as scattered standalone repositories built between hackathons; this repository modernizes them (TypeScript 5.9, ESM+CJS dual output, Node >= 20) and publishes them all under the @yingyeothon npm scope with a single shared version.

Documentation

Start here — the guide is written to be enough on its own.

The platform	the whole yyt picture, and where these packages sit in it
Getting started	an empty repository to a game running on a q channel
The game actor / Actor system	the game loop on Lambda, and the substrate under it
The realtime client	the browser client: states, close codes, backoff
Key-value store	announcements and per-player records over the channel JWT
Storage / Authentication / Logging	repositories and CAS, $connect authorizers, what never to log
Redis and sockets / Building blocks	the transport floor, and the three small leaves
Operations / Troubleshooting	limits, TTLs, concurrency, and symptom to cause

Runnable, compiled examples live in examples/, and every one of them runs with no AWS credentials, no Docker and no deployed gateway.

Packages

Package	Description
@yingyeothon/codec	Tiny codec abstraction (Codec + jsonCodec)
@yingyeothon/logger	Minimal structured logger with severity filtering
@yingyeothon/event-broker	Type-safe async event broker
@yingyeothon/logger-slack	Slack-webhook log writer for @yingyeothon/logger
@yingyeothon/logger-s3	Buffered log writer flushing into S3 via s3-cache-bridge
@yingyeothon/naive-socket	Minimal TCP/TLS client with queueing and reconnect
@yingyeothon/naive-redis	Minimal Redis client built on naive-socket (incl. pub/sub)
@yingyeothon/s3-cache-bridge-client	HTTP client for the s3-cache-bridge server
@yingyeothon/repository	Key-value repository abstractions + in-memory impl
@yingyeothon/repository-redis	Redis-backed repository
@yingyeothon/repository-s3	S3-backed repository
@yingyeothon/repository-dynamodb	DynamoDB-backed repository (TTL + conditional writes)
@yingyeothon/actor-system	Lightweight actor system (queue/lock/awaiter)
@yingyeothon/actor-system-redis	Redis-backed actor system support
@yingyeothon/actor-system-lambda	AWS Lambda glue for the actor system
@yingyeothon/lambda-authorizer	API Gateway TOKEN and REQUEST authorizer helpers
@yingyeothon/lambda-authorizer-jwt	JWT-issuing and JWT-verifying API Gateway authorizers
@yingyeothon/lambda-gamebase	Serverless WebSocket game framework on AWS Lambda
@yingyeothon/gamebase-all-together	Wait/running stage game loop plugin for lambda-gamebase
@yingyeothon/gamebase-client	Browser-capable client SDK for the yyt WebSocket gateway
@yingyeothon/kvstore-client	Game client for the yyt key-value store (/kv/*)

Dependency graph

graph LR
  naive-socket --> logger
  naive-redis --> logger
  naive-redis --> naive-socket
  logger-slack --> logger
  logger-s3 --> logger
  logger-s3 --> s3-cache-bridge-client
  repository-redis --> codec
  repository-redis --> logger
  repository-redis --> naive-redis
  repository-redis --> repository
  repository-s3 --> codec
  repository-s3 --> repository
  repository-dynamodb --> codec
  repository-dynamodb --> repository
  actor-system --> logger
  actor-system-redis --> actor-system
  actor-system-redis --> codec
  actor-system-redis --> logger
  actor-system-redis --> naive-redis
  actor-system-lambda --> actor-system
  actor-system-lambda --> logger
  lambda-authorizer --> logger
  lambda-authorizer-jwt --> lambda-authorizer
  lambda-authorizer-jwt --> logger
  lambda-gamebase --> actor-system
  lambda-gamebase --> actor-system-redis
  lambda-gamebase --> logger
  lambda-gamebase --> naive-redis
  gamebase-all-together --> lambda-gamebase
  gamebase-all-together --> logger
  gamebase-client --> codec
  gamebase-client --> logger
  kvstore-client --> logger

Loading

That graph is the only exact edge list; The platform shows the same packages by role instead, so there is never a second one to keep true.

API design rules shared by all packages are documented in CONVENTIONS.md.

Development

Requirements: Node >= 20, pnpm 11 (pinned via packageManager), Docker (for Redis testcontainers-based integration tests).

pnpm install
pnpm build        # tsup dual ESM+CJS+types for every package (topological order)
pnpm lint         # eslint (type-aware)
pnpm check:docs   # mermaid parses, links/anchors, orphan pages, README<->exports
pnpm typecheck    # tsc --noEmit per package (build first: workspace types resolve from dist)
node scripts/link-service.mjs link   # point ~/git/yyt.life/service (+ its examples) at this checkout instead of npm
node scripts/link-service.mjs unlink # back to npm before committing there
pnpm test         # vitest across all packages (spins up Redis containers)
pnpm coverage     # with v8 coverage and thresholds

pnpm install also registers .githooks/ (via core.hooksPath), whose pre-push hook runs the full CI gate — build, lint, format:check, typecheck, coverage — so a push that would fail CI is rejected locally. Set SKIP_CI_GATE=1 to bypass it once.

Every package ships dual ESM/CJS with type definitions via an exports map, targets Node >= 20, and exposes its whole public API as named exports from the package root (legacy deep imports such as @yingyeothon/naive-redis/lib/get are gone — see each package README's migration notes).

Release

All packages share one version. To release:

1. Run the Release workflow from the GitHub Actions tab with the version to publish (e.g. 2.0.0; it must exceed every version already published for any package).
2. The workflow stamps that version into every package, builds and tests, commits Release vX.Y.Z, tags that commit, pushes commit and tag atomically, publishes all packages with pnpm -r publish and npm provenance, and creates the GitHub Release.

The committed version fields therefore always equal the last release, and the tag points at the commit that was published. Publishing auth uses npm Trusted Publishing via the workflow's id-token: write permission; no npm token is stored. A package name that is new to npm needs one manual scripts/bootstrap-publish.sh run first so its Trusted Publisher can be registered.