@happyvertical/smrt-assets

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 3.3万

Asset management system with versioning, metadata, and AI-powered operations for SMRT framework

原始使用文档
文档目录12 节
  1. Feature recipes
  2. Installation
  3. Usage
  4. Portable local storage
  5. API
  6. Models (SmrtObject)
  7. Collections (SmrtCollection)
  8. Utilities
  9. Types
  10. Dependencies
  11. Native private attachments
  12. Polymorphic junction collection types

@happyvertical/smrt-assets

Provider-agnostic asset management with versioning, type classification, metadata fields, and generic/provenance associations.

AssetAssociation is the generic exception path for linking assets to arbitrary objects when there is not a model-owned noun join table. Base/domain-owned relationships should use dedicated joins such as content_assets, profile_assets, event_assets, place_assets, and product_assets.

Feature recipes

assets.library provides the model-backed file and media library: assets, folders, classifications, statuses, and metadata definitions. assets.attachments adds record attachment provenance and requires the library. They share the Files and media catalog card and the Assets navigation section, and both embed user-facing help in the generated manifest. The recipes publish browser-safe mock fixture exports from @happyvertical/smrt-assets/playground. AssetManager needs host persistence callbacks and AttachmentPanel needs record-scoped authorized attachments, so neither is declared as a standalone placement. Storage providers remain application-owned, so the recipes declare no provider.

The package playground is a Mock preview. Its asset grid uses in-memory props and data-URI thumbnails, and its attachment panel demonstrates supplied native form data only. It never performs a real network upload or creates public storage URLs.

Installation

pnpm add @happyvertical/smrt-assets

Usage

import {
  Asset, AssetCollection,
  AssetType, AssetStatus, AssetMetafield,
  AssetAssociation, AssetAssociationCollection,
  Folder, FolderCollection,
  AssetStore,
} from '@happyvertical/smrt-assets';

// Create lookup records
const imageType = new AssetType({ slug: 'image', name: 'Image' });
await imageType.save();

const published = new AssetStatus({ slug: 'published', name: 'Published' });
await published.save();

// Create an asset
const photo = new Asset({
  name: 'Product Photo',
  slug: 'product-photo-001',
  sourceUri: 's3://bucket/products/photo-001.jpg',
  mimeType: 'image/jpeg',
  typeSlug: 'image',
  statusSlug: 'published',
  version: 1,
});
await photo.save();

// Versioning -- chain via primaryVersionId, increment version number
const v2 = new Asset({
  ...photo, slug: 'product-photo-002', version: 2, primaryVersionId: photo.id,
  sourceUri: 's3://bucket/products/photo-002.jpg',
});
await v2.save();

// Derivatives via sourceAssetId (renamed from `parentId` in R3-D)
const thumb = new Asset({
  name: 'Thumbnail', slug: 'product-photo-001-thumb', sourceAssetId: photo.id,
  sourceUri: 's3://bucket/products/photo-001-thumb.jpg',
  mimeType: 'image/jpeg', typeSlug: 'image', statusSlug: 'published',
});
await thumb.save();

// Generic/provenance association -- link asset to an arbitrary object
const assoc = new AssetAssociation({
  assetId: photo.id,
  metaType: 'Image',
  metaId: 'derived-image-123',
  role: 'derivation-source',
  sortOrder: 0,
});
await assoc.save();

// Base/domain-owned asset relationships should use dedicated noun joins instead:
// content_assets, profile_assets, event_assets, place_assets, product_assets

// Folder organization (its own SmrtHierarchical model, `folders` table)
const folder = new Folder({ name: 'Product Images', slug: 'product-images' });
await folder.save();
// Move an asset into a folder
photo.folderId = folder.id;
await photo.save();

// AssetStore -- provider-agnostic file I/O + record creation
const store = await new AssetStore(assetRoot, collection).initialize();
await store.store('screenshot', buffer, { mimeType: 'image/png' });

Portable local storage

For a new desktop installation, pass the same portable storage configuration to each asset runtime, worker, and service that handles its managed files:

const assets = await createAssetRuntime({
  db,
  storage: { type: 'local', basePath: assetRoot, locatorMode: 'relative' },
});

Use an absolute, app-owned assetRoot. The store persists asset-local:<key>, for example asset-local:document/17f6.txt. The key is a raw, slash-separated path under the configured root and contains no URL escaping. Use ASCII letters, digits, underscores, and hyphens in type slugs and IDs. The store rejects traversal, absolute keys, Windows device names, links at or below the root, and non-regular files. Keep the root and its contents under app control; the filesystem checks assume no concurrent changes by an untrusted local process.

When copying an installation, copy the database and the asset directory together, keep each file's path within the directory, and set basePath to the copied directory. Read, preserve, and remove assets through the runtime. A storage resolver may choose a path for a portable write, but later reads and deletes must use the stored key in the built-in local filesystem for that runtime.

The option changes new writes only. Existing local options and S3 locators keep their formats. A built-in local store can read portable locators whether or not it opts in to writing them. In portable mode, an existing file:// locator can still be read or removed when it identifies a valid key inside the configured root; changing the root does not relocate such records. Start with fresh desktop data or handle existing absolute locators before moving an installation.

API

Models (SmrtObject)

ExportDescription
AssetCore asset with versioning (primaryVersionId, version), derivation chain (sourceAssetId), sourceUri, mimeType, typeSlug, statusSlug, ownerProfileId
AssetAssociationGeneric/provenance polymorphic join: assetId + metaType + metaId + role + sortOrder; not for base/domain-owned joins that already have noun tables
AssetTypeLookup table for asset type classification
AssetStatusLookup table for lifecycle status
AssetMetafieldCustom metadata field definitions with JSON validation rules
FolderHierarchical container for assets; own folders table extending SmrtHierarchical

Collections (SmrtCollection)

ExportDescription
AssetCollectionCollection for Asset
AssetAssociationCollectionCollection for AssetAssociation
AssetTypeCollectionCollection for AssetType
AssetStatusCollectionCollection for AssetStatus
AssetMetafieldCollectionCollection for AssetMetafield
FolderCollectionCollection for Folder

Utilities

ExportDescription
AssetStoreProvider-agnostic file I/O that writes buffers to storage and creates Asset records

Types

ExportDescription
AssetOptionsOptions for Asset constructor
AssetAssociationOptionsOptions for AssetAssociation constructor
AssetTypeOptionsOptions for AssetType constructor
AssetStatusOptionsOptions for AssetStatus constructor
AssetMetafieldOptionsOptions for AssetMetafield constructor
FolderOptionsOptions for Folder constructor
StoreOptionsOptions for AssetStore.store()
ProviderOptionsProvider configuration for AssetStore

Dependencies

PackagePurpose
@happyvertical/smrt-coreORM base (SmrtObject, SmrtCollection)
@happyvertical/smrt-tagsTag integration (addTag/removeTag on assets)
@happyvertical/smrt-tenancyOptional tenant scoping
@happyvertical/filesProvider-agnostic filesystem for AssetStore

Native private attachments

AttachmentPanel, AttachmentList and AttachmentUpload compose authorized private links, caller-supplied version history, and native multipart uploads. They preserve request identity and failed-action metadata without deriving public storage URLs. See the attachment contract for public types, native payloads, recovery, and server responsibilities.

Pass onremove(attachment) and/or removeAction (native POST of the attachment id) to add a confirmed per-attachment Remove button; see "Removing attachments" in the contract.

Polymorphic junction collection types

AssetAssociationCollection extends SmrtJunctionBase, sharing byRight, ordering, positioning, and registration guards with ordinary junctions. Its byLeft, attach, detach, and setLinks methods still require both metaType and metaId; they do not implement the single-owner SmrtJunction contract. Use instanceof SmrtJunctionBase when recognizing either kind of junction. Asset associations no longer satisfy instanceof SmrtJunction.

After building the workspace, node scripts/verify-packed-junction-types.mjs checks actual core/assets tarballs in the standard Bundler mode with skipLibCheck: false, inherited result types, and negative owner-argument tests. Full NodeNext declaration portability is tracked separately in #3524.

The consumer fixture installs declared dependencies in a temporary directory with no ancestor node_modules; it never links producer dependencies. It retains the project’s public registry routing without copying credentials. Set SMRT_PACKED_EVIDENCE_DIR to retain tarballs and the consumer lockfile. For an explicitly separate upstream-candidate proof, SMRT_PACKED_OVERRIDES may name a JSON file of pnpm overrides; such a proof does not establish that the normal published dependency graph passes.

版本与发布记录

@happyvertical/smrt-assets 共发布 366 个版本,首次发布于 2026/06/23;过去 12 个月发布了 366 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-assets 的常见问题

@happyvertical/smrt-assets 是什么?

Asset management system with versioning, metadata, and AI-powered operations for SMRT framework

如何安装 @happyvertical/smrt-assets?

在项目目录运行 npm install @happyvertical/smrt-assets,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-assets 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-assets 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-assets 可以商用吗?

@happyvertical/smrt-assets 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-assets 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-assets 在 2026/10/17 – 2026/11/15 这 30 天内被下载 32,593 次,日均约 1,086 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-assets 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 366 个版本,其中过去 12 个月发布了 366 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。