@happyvertical/files

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

File system utilities for local and remote file operations

原始使用文档
文档目录14 节
  1. Installation
  2. Usage
  3. Factory Function
  4. Google Drive
  5. Drive catalog discovery and pinned acquisition
  6. File Operations
  7. Fetch Utilities
  8. Secure ZIP Manifest Inspection
  9. Error Handling
  10. Bounded reads and create-without-overwrite
  11. Legacy Functions
  12. Providers
  13. API Overview
  14. Dependencies

@happyvertical/files

Unified filesystem interface for the HAVE SDK. Provides a consistent API across local filesystem (Node.js fs/promises) and Google Drive, with rate-limited fetch utilities and legacy compatibility helpers.

Installation

pnpm add @happyvertical/files

Released to npm.happyvertical.com and mirrored to public npm, which can lag (see the root README's installation notes). Depends on @happyvertical/utils.

Usage

Factory Function

import { getFilesystem } from '@happyvertical/files';

// Local filesystem (default)
const fs = await getFilesystem({ type: 'local', basePath: '/app/data' });

await fs.write('output/result.txt', 'Hello, world!');
const content = await fs.read('config.json');
const exists = await fs.exists('config.json');

// List files with filtering
const files = await fs.list('.', { filter: /\.json$/, detailed: true });
for (const file of files) {
  console.log(`${file.name}: ${file.size} bytes, ${file.mimeType}`);
}

Google Drive

import { getFilesystem } from '@happyvertical/files';

const fs = await getFilesystem({
  type: 'gdrive',
  clientId: 'xxx',
  clientSecret: 'yyy',
  refreshToken: 'zzz',
});

await fs.write('documents/readme.txt', 'Hello from Drive');
const content = await fs.read('documents/readme.txt');

Supports OAuth2, service account keys, and short-lived access tokens. Google Docs native formats are automatically exported (Docs → text, Sheets → CSV, etc.) for the legacy path API.

Drive catalog discovery and pinned acquisition

GoogleDriveProvider also exposes ID-based Drive operations for catalog adapters. listMetadataPage() performs metadata-only, one-folder pagination; persist the returned nextPageToken and enqueue folder IDs yourself for a resumable traversal. It never requests media or exports content.

import { GoogleDriveProvider } from '@happyvertical/files';

const drive = new GoogleDriveProvider({
  type: 'gdrive',
  accessToken: process.env.DRIVE_READ_TOKEN,
  folderId: 'configured-source-root',
  // Optional additional source roots and shared-drive support:
  allowedFolderIds: ['configured-source-root'],
  sharedDriveId: 'shared-drive-id',
});

const page = await drive.listMetadataPage({ pageToken: checkpoint });
// page.entries include stable id, revisionId, parents, driveId, and shortcut metadata.

const snapshot = await drive.acquireById(page.entries[0].id, {
  expectedRevision: page.entries[0].revisionId,
  maxBytes: 25 * 1024 * 1024,
  // Native Docs/Sheets/Slides require an intentional export format.
  exportMimeType: 'application/pdf',
});

acquireById() validates ancestor scope against allowedFolderIds, validates shortcut targets independently, streams with a hard byte bound, checks the Drive revision before and after acquisition, and returns a SHA-256 content hash. Use application/pdf for native files that need layout-preserving printing. It never stores credentials in returned metadata.

File Operations

await fs.copy('source.txt', 'backup/source-copy.txt');
await fs.move('temp.txt', 'archive/temp.txt');
await fs.createDirectory('secure-data', { mode: 0o700 });
await fs.delete('temporary-file.txt');

const stats = await fs.getStats('document.pdf');
console.log(`${stats.size} bytes, modified ${stats.mtime}`);

Fetch Utilities

Rate-limited HTTP fetch helpers for downloading remote content:

import { fetchText, fetchJSON, fetchBuffer, fetchToFile, addRateLimit } from '@happyvertical/files';

// Set per-domain rate limits
addRateLimit('api.github.com', 30, 60000);

const html = await fetchText('https://example.com');
const data = await fetchJSON('https://api.example.com/data');
const buf = await fetchBuffer('https://example.com/image.png');
await fetchToFile('https://example.com/file.zip', './downloads/file.zip');

Secure ZIP Manifest Inspection

Inspect untrusted ZIP metadata before deciding whether to accept an upload. @happyvertical/files/archive is a standalone browser-safe entry using only Web APIs, with no Node imports. The same API remains exported from the Node root:

import {
  inspectZipManifest,
  ZipManifestError,
  ZipManifestLimitError,
} from '@happyvertical/files/archive';

try {
  const manifest = inspectZipManifest(zipBytes, {
    maxEntries: 2_000,
    maxEntryUncompressedBytes: 50 * 1024 * 1024,
    maxTotalUncompressedBytes: 500 * 1024 * 1024,
  });

  const files = manifest.entries
    .filter((entry) => entry.type === 'file')
    .map(({ path, size }) => ({ path, size }));
} catch (error) {
  if (error instanceof ZipManifestLimitError) {
    console.error(error.limit, error.actual, error.maximum);
  } else if (error instanceof ZipManifestError) {
    console.error(error.code, error.message);
  }
}

inspectZipManifest() reads and cross-checks central-directory and local-header metadata only. It does not decompress or materialize file bodies. Paths are returned with / separators and ./empty segments removed; names containing ordinary spaces remain valid. The whole archive is rejected for parent traversal, absolute/drive-qualified paths, NTFS alternate data stream paths containing colons, NUL bytes, Unix symlinks and special files, Windows reparse points and reserved device names, path segments ending in dots or spaces, case-insensitive or Unicode-normalization path collisions, file/descendant path conflicts, overlapping local entry ranges, or unreferenced data before the central directory.

Default limits are 10,000 entries, 200 MiB per entry, 2 GiB aggregate declared uncompressed size, and 1,024 encoded path bytes. Entry count includes directory entries, and aggregate size includes every entry. All limits are configurable with non-negative safe integers. The entry limit also bounds cumulative central-directory work while disambiguating end records in hostile comments.

Policy is deliberately strict: ZIP64, encrypted, multi-disk, malformed, truncated, ambiguous-end-record, and non-UTF-8-name archives are rejected with typed errors. Stored entries must also declare identical compressed and uncompressed sizes, and each local header and compressed payload must occupy a distinct range. Those referenced ranges must collectively cover every byte before the central directory, so archive preambles, padding gaps, and local entries omitted from the central directory are rejected. Signed and unsigned classic data descriptors are accepted for stored and compressed entries only at payloadStart + centralCompressedSize. Their CRC and sizes must match the central directory, and local fields must be zero or matching. Descriptor bytes participate in the same overlap and complete-coverage checks; signatures inside payloads are never scanned. These are metadata checks: consumers must still bound actual inflation and verify output size and CRC independently. Entry names use strict UTF-8 decoding whether or not the UTF-8 flag is set. Leading UTF-8 BOMs are rejected because filename decoders disagree on whether the BOM is part of the extracted path; common macOS ZIPs with valid UTF-8 names remain compatible. PKWARE alternate-encoding, Info-ZIP, and Xceed path extra fields are rejected so an extractor cannot select a different path or character encoding from the one inspected. PKWARE and ASi Unix extra fields are likewise rejected because they can supply link targets; libarchive's xl field is rejected because it can override the inspected file type. Unix file-type bits are honored only for Unix- or Darwin-origin central headers; file-type bits claimed by DOS, NTFS, or other creator systems are rejected. These alternate-metadata cases, along with contradictory Unix file and directory attributes, use UnsupportedZipFeatureError with the ambiguous-metadata feature. This API is a metadata preflight, not an extraction API; consumers that later extract an accepted archive must still use an extraction destination and library with equivalent path and symlink protections.

Error Handling

import { FileNotFoundError, PermissionError, DirectoryNotEmptyError } from '@happyvertical/files';

try {
  await fs.read('missing.txt');
} catch (error) {
  if (error instanceof FileNotFoundError) {
    console.error('Not found:', error.path);
  } else if (error instanceof PermissionError) {
    console.error('Permission denied:', error.path);
  }
}

Bounded reads and create-without-overwrite

All providers accept a byte ceiling for reads and reject content above it with FileSizeLimitExceededError. The S3 provider enforces the ceiling while it consumes the response stream, including responses without a content length.

const object = await fs.read('objects/sha256.bin', {
  raw: true,
  maxBytes: 10 * 1024 * 1024,
});

await fs.write('objects/sha256.bin', object, { overwrite: false });

overwrite: false is an atomic create operation for the local provider. S3 fails with ConditionalWriteUnsupportedError before sending a request unless its options explicitly declare conditionalWriteStrategy: 'if-none-match'. Set that option only when the resolved endpoint's documented contract guarantees that PUT honors If-None-Match: *; accepting the header without enforcing it is insufficient. The setting is explicit even for native AWS S3 because AWS SDK environment configuration can redirect endpoints. An existing destination raises FileExistsError and is never overwritten. A concurrent S3 operation raises the retryable ConditionalWriteConflictError (EAGAIN).

Legacy Functions

Standalone functions from the original API, still exported for backward compatibility:

import { isFile, isDirectory, ensureDirectoryExists, download, listFiles } from '@happyvertical/files';

const fileStats = isFile('/path/to/file.txt'); // synchronous
const isDir = isDirectory('/path/to/dir');     // synchronous
await ensureDirectoryExists('/path/to/new/dir');
await download('https://example.com/file.pdf', './file.pdf');
const files = await listFiles('/path/to/dir', { match: /\.json$/ });

Providers

ProviderStatusOptions
LocalImplementedbasePath?
Google DriveImplementedclientId, clientSecret, refreshToken (or serviceAccountKey / accessToken)
S3Implementedregion, bucket, accessKeyId?, secretAccessKey?, endpoint?, conditionalWriteStrategy?
WebDAVTypes onlybaseUrl, username, password

API Overview

Factory: getFilesystem(options), registerProvider(type, factory), getAvailableProviders(), isProviderAvailable(type), getProviderInfo(type)

Provider classes: LocalFilesystemProvider, GoogleDriveProvider, S3FilesystemProvider

Interface methods: exists, read, write, delete, copy, move, createDirectory, list, getStats, getMimeType, upload, download, downloadWithCache, cache.get/set/clear, getCapabilities

Fetch: fetchText, fetchJSON, fetchBuffer, fetchToFile, addRateLimit, getRateLimit

Archive inspection: inspectZipManifest, DEFAULT_ZIP_MANIFEST_LIMITS, ZipManifestError, InvalidZipArchiveError, UnsafeZipEntryError, ZipManifestLimitError, UnsupportedZipFeatureError

Errors: FilesystemError, FileNotFoundError, PermissionError, DirectoryNotEmptyError, InvalidPathError

Legacy: isFile, isDirectory, ensureDirectoryExists, download, upload, downloadFileWithCache, listFiles, getCached, setCached, getMimeType

Dependencies

  • @happyvertical/utils — temp directory management
  • googleapis / google-auth-library — Google Drive provider

版本与发布记录

@happyvertical/files 共发布 132 个版本,首次发布于 2026/06/23;过去 12 个月发布了 132 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/files 的常见问题

@happyvertical/files 是什么?

File system utilities for local and remote file operations

如何安装 @happyvertical/files?

在项目目录运行 npm install @happyvertical/files,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-files-context,可以用 npx have-files-context 直接运行。

@happyvertical/files 支持 TypeScript 吗?

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

@happyvertical/files 支持 ESM 还是 CommonJS?

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

@happyvertical/files 可以商用吗?

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

@happyvertical/files 的下载量有多少?

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

@happyvertical/files 还在维护吗?

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