DDD-oriented media store: put bytes in storage and get them back under one contract across languages.
Core operations are Store / Delete / Get (plus PresignGet where supported), with:
- Local FS and S3-compatible adapters
- Optional media DB metadata (table name + column map)
- Image pipeline (compress / resize / thumbnails), SVG sanitize, PDF first-page thumbnails (renderer injection)
Versions are independent per language. Check the current line in each port’s README / VERSION / package.json. Today Go and npm both ship 0.10.0 (dependency updates).
| Port | Package | Language hub (install, Config, CLI details) |
|---|---|---|
| Go | github.com/b4moss/median/packages/go |
packages/go/README.md |
| TypeScript | @b4moss/median |
packages/js/README.md |
| PHP | — | Not scheduled — docs/plans/unscheduled/packages-php.md |
This root README is the shared host workflow. Port-specific install commands, import paths, New / createMedian examples, and full CLI flags live only in the language hubs above.
| Go host | JS / Node host | |
|---|---|---|
| Runtime | Go 1.26+ | Node.js 24+ |
| Package | github.com/b4moss/median/packages/go@v0.10.0 |
@b4moss/median@0.10.0 |
| DB (optional) | GORM-backed dialect via crudian | better-sqlite3 at runtime; DDL dump still supports mysql / postgres / sqlite3 |
| Storage | Local path and/or S3-compatible endpoint | Same |
You do not need this monorepo cloned to use published packages. Clone only for contributing or running E2E.
Recommended production path when your app owns migrations.
- Go →
packages/go/README.md
go get github.com/b4moss/median/packages/go@v0.10.0 - JS →
packages/js/README.md
npm install @b4moss/median
Use the same values for the DDL dump and for runtime config.
| Setting | Default | Alternatives |
|---|---|---|
| Table | media |
any identifier accepted by NormalizeTableName |
| ID strategy | auto_increment |
uuid_v4 · uuid_v7 · ulid |
| Dialect | — (required for dump) | mysql | postgres | sqlite3 |
Skip this step only if you run without DB (storage-only) — see Without a media DB below.
median does not run production migrate for you. Generate SQL and commit it to the host migrate tool (goose, Prisma, Flyway, knex, …).
# Go
go run github.com/b4moss/median/packages/go/cmd/median@v0.10.0 \
migrate dump --dialect postgres --id-strategy auto_increment --table media \
> migrations/XXXX_median_media.sql
# JS
npx @b4moss/median migrate dump \
--dialect postgres --id-strategy auto_increment --table media \
> migrations/XXXX_median_media.sql| Stream | Content |
|---|---|
| stdout | SQL only (safe to redirect into a migration file) |
| stderr | errors / usage |
| Exit code | 0 on success, non-zero on bad flags |
- Spec:
docs/specs/ddl-cli/ - Schema reference:
migrations/README.md
Then run your usual migrate up in CI / deploy.
Existing table with different column names? Skip the dump. Map columns in Config instead (docs/specs/db-media/).
Order matters:
- Host migrate applies the media table
- App boots and constructs median with the same
table/id-strategy/ dialect assumptions - Call Store / Get / Delete
Language-specific New / createMedian wiring: Go and JS hubs above.
Conceptually (pseudo):
Store(bytes, size, { mime, filename, … })
→ writes object to storage
→ optionally inserts a media row (file_path / file_name / …)
→ returns { path, hash, id?, variants?, … }
Get(path)
→ reads object (and optional DB enrichment)
Delete(path)
→ removes object (+ DB row / variants when configured)
Public field name path remains the storage-relative key; the DB column is file_path (v0.7+).
Configure pipeline and storages in the language Config. Details and constraints (e.g. PDF renderer must be injected) are in the language hub and docs/specs/.
- Unit tests:
packages/go→go test ./…·packages/js→npm test - E2E (RustFS + LocalFS, Go + JS):
./e2e/run.shor Actionse2e.ymlworkflow_dispatch— seedocs/specs/e2e/
Omit DB config entirely. median still Store / Get / Delete against Local FS or S3; there is no metadata row and no migrate dump step. Wiring examples: language hubs (leave DB / db unset).
| Pitfall | Fix |
|---|---|
| Dump flags ≠ runtime Config | Match --table / --id-strategy / dialect with TableName / IDStrategy |
Expecting median to migrate up in prod |
Use host migrate + migrate dump; MigrateUp / migrateUp are for tests / throwaway DBs |
| Redirecting stderr into the SQL file | Capture stdout only; check stderr separately |
Go go get 404 from proxy |
Module path is …/packages/go; tag is packages/go/vX.Y.Z — see go-module-path |
Confusing public path with DB column |
API field stays path; physical column is file_path |
| PDF thumbs with no renderer | Inject a renderer in Config; median does not ship a PDF engine |
median migrate dump --dialect <mysql|postgres|sqlite3> [--id-strategy …] [--table …]
| Go | JS | |
|---|---|---|
| Run | go run …/cmd/median@v0.10.0 migrate dump … |
npx @b4moss/median migrate dump … |
| Install binary | go install …/cmd/median@v0.10.0 |
npm i -g @b4moss/median (or local npx) |
| Library twin | db.CreateMediaSQL |
createMediaSQL |
Full flags and examples: language hubs · migrations/README.md.
| Doc | Contents |
|---|---|
docs/README.md |
Product pillar (purpose, scope, tech policy) |
docs/roadmap.md |
Milestones |
docs/specs/ |
Current specs (domain-oriented) |
docs/plans/ |
Upcoming plans (PHP unscheduled) |
docs/tests/ |
TDD acceptance specs |
| b4moss/charter v1 | Charter (AGENTS.md) |
migrations/ |
Schema reference (goose-oriented source of truth) |
e2e/ |
E2E harness |
.github/CI.md |
CI/CD / publish tags |
packages/go/README.md |
Go language hub |
packages/js/README.md |
JS language hub |
MIT © Bicycle for Mind LLC. — see LICENSE.