wyuc 04b70f0359
feat(storage): scaffold @openmaic/storage — KV + asset primitives (browser) (#857) (#858)
* feat(storage): scaffold @openmaic/storage — KV + asset primitives (browser) (#857)

First executable slice of the @openmaic/storage RFC (#779, Part 1): a pure,
app-agnostic persistence package depending only on @openmaic/dsl.

- Add the DSL-owned `StorageProvider` asset seam to @openmaic/dsl
  (put(blob)->ref / resolve(ref)->url / remove), typed against a structural
  `BinaryBlob` so the pure DSL keeps `lib: ES2022` (no DOM).
- `KVStore` (device/account scopes) + `BrowserKVStore` over localStorage.
- `BrowserAssetProvider`: content-addressed (sha256) bytes in IndexedDB,
  resolved to object URLs; identical bytes de-duplicate.
- `kvPersistStorage`: adapt a KVStore into a zustand `persist` storage
  (pure util; app store wiring is a follow-up).
- Implementation-agnostic contract suites (KV + StorageProvider), run against
  the browser backends so future backends prove equivalence.
- Machine-enforce the package import boundary in eslint (no `@/...`),
  mirroring the @openmaic/renderer boundary.

Backends take their Storage/IDBFactory by injection, so the package is
testable without a browser. Deferred to later Part-1 steps: wiring the app's
zustand stores + ad-hoc localStorage through KVStore (needs a legacy-key
compat migration), DocumentStore/RuntimeStore, and the HTTP backend.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(storage): address cross-review findings

- BrowserAssetProvider: resolve writes on transaction.oncomplete (not
  request.onsuccess) so a commit-time abort (e.g. QuotaExceeded) can't be
  reported as durable success.
- BrowserAssetProvider.openDb: don't memoize a rejected open — a transient IDB
  failure no longer bricks the provider; the next call retries.
- BrowserAssetProvider.resolve: memoize the resolution per ref so concurrent
  resolves share one object URL instead of orphaning a second one.
- BrowserKVStore.set: treat a value JSON can't represent (undefined / function
  / symbol) as a removal, instead of writing a literal "undefined" that throws
  on the next get (and would reject zustand rehydration).
- Tests: build contract Blobs from strings (a Uint8Array BlobPart fails the
  root tsconfig typecheck under TS 5.7+ typed-array generics); reset the
  object-URL registry per test; add regression tests for set(undefined),
  concurrent-resolve, and actual de-dup (one stored row).
- Drop @openmaic/storage from the root postinstall build chain: nothing imports
  it yet, so building it on every install added latency and coupled its build
  failures to importer/renderer/sync. It re-joins when the app consumes it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(storage): don't cache a rejected resolve promise

Second cross-review pass caught that the per-ref resolve memoization
reintroduced the same rejected-promise-caching bug just fixed in openDb: a
transient IndexedDB failure inside resolve() left the rejected promise in the
`urls` map, so every later resolve(ref) replayed the rejection and never
retried. Evict the entry on rejection (mirroring the null-miss path), and add
a regression test that fails a resolve's IDB open once and asserts the next
resolve recovers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(storage): review — coherent re-put contentType + restore bootstrap build

Addresses @cosarah's review on #858:

- BrowserAssetProvider.put: invalidate (revoke + drop) any cached object URL
  for the ref after a write, so a re-put of the same bytes with a corrected
  contentType is reflected by resolve() instead of a stale, cache-warmth-
  dependent MIME type. remove() reuses the same invalidateUrl helper. Adds a
  regression test (put type="" -> resolve -> put same bytes type="image/png"
  -> resolve now reports image/png).
- Restore @openmaic/storage to the root postinstall build chain: the package
  publishes dist/*, so a clean install must build it or workspace consumers
  resolving it via exports would fail until a manual --filter build.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-06 17:12:10 +08:00

56 lines
1.3 KiB
JSON

{
"name": "@openmaic/storage",
"version": "0.0.1",
"description": "The MAIC pluggable persistence layer: KV / asset primitives with swappable backends (browser default, HTTP later), depending only on @openmaic/dsl.",
"type": "module",
"main": "./dist/index.js",
"module": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
},
"files": [
"dist",
"README.md",
"LICENSE"
],
"sideEffects": false,
"scripts": {
"clean": "rm -rf dist",
"build": "rm -rf dist && tsc -p tsconfig.json",
"dev": "tsc -p tsconfig.json --watch",
"typecheck": "tsc -p tsconfig.json --noEmit",
"test": "vitest run",
"test:watch": "vitest",
"prepublishOnly": "pnpm run build"
},
"keywords": [
"maic",
"storage",
"persistence",
"kv",
"indexeddb"
],
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/THU-MAIC/OpenMAIC",
"directory": "packages/@openmaic/storage"
},
"publishConfig": {
"registry": "https://registry.npmjs.org",
"access": "public"
},
"dependencies": {
"@openmaic/dsl": "workspace:*"
},
"devDependencies": {
"fake-indexeddb": "^6.0.0",
"typescript": "^5",
"vitest": "^4.1.8"
}
}