skills/plugins/library-navigator/skills/sp-storage-uri-plugin-bundle/SKILL.md

name, description

name	description
sp-storage-uri-plugin-bundle	Bundle URI plugin for @suaveplan/storage-uri — serves packed asset bundles over HTTP with range support, LRU cache, safe fetch shim, and OTel metrics.

sp-storage-uri-plugin-bundle

Symbol	Kind	Responsibility
bundleUriPlugin	Function	Creates bundle:// URI plugin
validateOptions	Function	Validates bundle plugin options
BundleStorageShim	Class	Shim adapting bundle storage to URI plugin interface
safeFetch	Function	Safe fetch with error handling
performExists	Function	Checks if bundle entry exists
performGetMetadata	Function	Reads bundle entry metadata
performRangeRead	Function	Reads byte range from bundle
buildRangeHeader	Function	Builds HTTP Range header
sliceForRange	Function	Slices buffer for byte range
validateRange	Function	Validates range request
parse	Function	Parses bundle:// URI
build	Function	Builds bundle:// URI
UriLruCache	Class	LRU cache for bundle responses
toReadableStream	Function	Converts response to readable stream
ensureNotAborted	Function	Throws if operation aborted
recordCacheHit	Function	OTel counter for cache hits
recordCacheMiss	Function	OTel counter for cache misses
recordRangeFallback	Function	OTel counter for range fallbacks
BUNDLE_URI_CODES	Constant	Error codes via defineCodes
BundleUriError	Class	Typed error with bundle URI codes
BundleUriPluginOptionsSchema	Schema	Zod schema for plugin options

File Structure: packages/persistence/storage/storage-uri-plugin-bundle/src/{factory,storage-shim,parse,range,cache,streaming,abort,otel,error-codes,types}/

Sibling packages:

• @suaveplan/storage-uri — URI resolver framework
• @suaveplan/packer-browser — asset bundling

Patterns:

Quick Start:

import { bundleUriPlugin } from "@suaveplan/storage-uri-plugin-bundle";
const plugin = bundleUriPlugin({ baseUrl: "https://cdn.example.com/bundles" });

Shim:

import { BundleStorageShim } from "@suaveplan/storage-uri-plugin-bundle";
const shim = new BundleStorageShim({ baseUrl });

Range read:

import { performRangeRead } from "@suaveplan/storage-uri-plugin-bundle";
const data = await performRangeRead({ url, range: { start: 0, end: 1024 } });

Constraints:

• Implements UriPlugin from @suaveplan/storage-uri
• bundle:// URIs reference packed asset bundles
• BundleStorageShim fetches bundles over HTTP with retry
• Range requests supported for partial asset loading
• UriLruCache caches bundle metadata and small responses
• safeFetch handles network errors with typed BundleUriError
• OTel instruments: cache hit/miss, range fallback, operations
• Error codes use defineCodes from @suaveplan/error

Checklist:

• bundleUriPlugin implements UriPlugin interface
• bundle:// URIs resolved to bundle assets
• BundleStorageShim fetches over HTTP
• Range requests return correct partial content
• UriLruCache caches metadata and responses
• safeFetch handles errors gracefully
• OTel metrics track cache effectiveness
• Error codes use defineCodes from @suaveplan/error