@crosscopy/clipboard 0.2.6 → 0.3.3

package/README.md

@@ -1,54 +1,210 @@
 # Clipboard
 
+[![NPM Version](https://img.shields.io/npm/v/@crosscopy/clipboard)](https://www.npmjs.com/package/@crosscopy/clipboard)
+[![CI](https://github.com/CrossCopy/clipboard/actions/workflows/CI.yml/badge.svg)](https://github.com/CrossCopy/clipboard/actions/workflows/CI.yml)
+
 **NPM Package**: https://www.npmjs.com/package/@crosscopy/clipboard
 
 **GitHub**: https://github.com/crosscopy/clipboard
 
-> This is a clipboard API npm package that allows you to copy and paste data to and from the clipboard.
-> There doesn't seem to be a good clipboard package for node.js (that supports data format beyond text), so I decided to make one.
-> Data Format Supported
->
-> - Text
-> - Image
-> - Rich Text Format
-> - Files
-> - HTML
+Cross-platform native clipboard for Node.js. Read, write, and watch the system clipboard with support for multiple data formats.
 
-## Acknowledgements
+### Supported Formats
+
+- Text
+- HTML
+- Rich Text (RTF)
+- Images (PNG binary / base64)
+- Files
+- Arbitrary binary buffers (custom format strings)
+
+## Install
+
+```bash
+npm install @crosscopy/clipboard
+# or
+yarn add @crosscopy/clipboard
+```
 
-- [ChurchTao/clipboard-rs](https://github.com/ChurchTao/clipboard-rs) is written in rust, which is used to provide the native clipboard support for this package across Linux, Windows and MacOS. This package is basically a wrapper around this rust package.
-  - https://crates.io/crates/clipboard-rs
-- [napi.rs](https://napi.rs/) was used to create the node.js addon for this package, so that API calls written in rust can be called from node.js.
+## Quick Start
+
+```typescript
+import {
+  getText, setText,
+  hasText, hasImage,
+  getImageBase64,
+  startWatch,
+} from '@crosscopy/clipboard'
+
+// Read & write text
+await setText('hello world')
+console.log(await getText()) // "hello world"
+
+// Check what's on the clipboard
+console.log(hasText())  // true
+console.log(hasImage()) // false
+
+// Watch for changes
+const watcher = startWatch(() => {
+  console.log('clipboard changed!')
+})
+// ... later
+watcher.stop()
+```
 
 ## API
 
-Detailed API function declarations can be found in the [index.d.ts](./index.d.ts).
+Full type declarations are in [`index.d.ts`](./index.d.ts).
+
+### Text
+
+| Function | Signature | Description |
+|---|---|---|
+| `hasText` | `() => boolean` | Check if clipboard contains text |
+| `getText` | `() => Promise<string>` | Read text from clipboard |
+| `setText` | `(text: string) => Promise<void>` | Write text to clipboard |
+
+```typescript
+import { hasText, getText, setText } from '@crosscopy/clipboard'
+
+await setText('copied!')
+if (hasText()) {
+  console.log(await getText())
+}
+```
+
+### HTML
+
+| Function | Signature | Description |
+|---|---|---|
+| `hasHtml` | `() => boolean` | Check if clipboard contains HTML |
+| `getHtml` | `() => Promise<string>` | Read HTML string from clipboard |
+| `setHtml` | `(html: string) => Promise<void>` | Write HTML string to clipboard |
+
+```typescript
+import { setHtml, getHtml } from '@crosscopy/clipboard'
+
+await setHtml('<b>bold</b>')
+console.log(await getHtml())
+```
+
+### Rich Text (RTF)
+
+| Function | Signature | Description |
+|---|---|---|
+| `hasRtf` | `() => boolean` | Check if clipboard contains RTF |
+| `getRtf` | `() => Promise<string>` | Read RTF string from clipboard |
+| `setRtf` | `(rtf: string) => Promise<void>` | Write RTF string to clipboard |
+
+### Image
+
+| Function | Signature | Description |
+|---|---|---|
+| `hasImage` | `() => boolean` | Check if clipboard contains an image |
+| `getImageBinary` | `() => Promise<Array<number>>` | Read image as PNG bytes |
+| `getImageBase64` | `() => Promise<string>` | Read image as base64-encoded PNG |
+| `setImageBinary` | `(imageBytes: Array<number>) => Promise<void>` | Write PNG bytes to clipboard |
+| `setImageBase64` | `(base64Str: string) => Promise<void>` | Write base64-encoded PNG to clipboard |
+
+```typescript
+import { hasImage, getImageBase64, setImageBinary } from '@crosscopy/clipboard'
+import { readFileSync } from 'fs'
 
-Or you can refer to the source code in [src/lib.rs](./src/lib.rs).
+// Write a PNG file to clipboard
+const png = readFileSync('screenshot.png')
+await setImageBinary(Array.from(png))
 
-## Sample
+// Read as base64
+if (hasImage()) {
+  const b64 = await getImageBase64()
+  console.log(`data:image/png;base64,${b64}`)
+}
+```
 
-```javascript
-import Clipboard from "@crosscopy/clipboard";
+### Files
 
-console.log(await Clipboard.getText());
+| Function | Signature | Description |
+|---|---|---|
+| `hasFiles` | `() => boolean` | Check if clipboard contains file references |
+| `getFiles` | `() => Promise<Array<string>>` | Read file paths from clipboard |
+| `setFiles` | `(files: Array<string>) => Promise<void>` | Write file paths to clipboard |
 
-console.log(await Clipboard.getHtml());
+```typescript
+import { hasFiles, getFiles } from '@crosscopy/clipboard'
 
-if (await Clipboard.hasImage()) {
-  console.log(await Clipboard.getImageBase64());
-} else {
-  console.log("No Image");
+if (hasFiles()) {
+  const paths = await getFiles()
+  console.log(paths) // ["/Users/you/file.txt", ...]
 }
 ```
 
-## Plan
+### Buffer (Custom Formats)
+
+| Function | Signature | Description |
+|---|---|---|
+| `getBuffer` | `(format: string) => Promise<Array<number>>` | Read raw bytes for a given format |
+| `setBuffer` | `(format: string, buffer: Array<number>) => Promise<void>` | Write raw bytes for a given format |
+
+```typescript
+import { setBuffer, getBuffer } from '@crosscopy/clipboard'
+
+await setBuffer('com.myapp.custom', [0x01, 0x02, 0x03])
+const data = await getBuffer('com.myapp.custom')
+```
+
+### Utilities
+
+| Function | Signature | Description |
+|---|---|---|
+| `availableFormats` | `() => Array<string>` | List all format types currently on the clipboard |
+| `clear` | `() => Promise<void>` | Clear the clipboard |
+
+### Clipboard Watcher
+
+Monitor clipboard changes using OS-native notifications.
+
+| Function / Method | Signature | Description |
+|---|---|---|
+| `startWatch` | `(callback: () => void) => ClipboardWatcherJs` | Start watching; returns a handle |
+| `watcher.stop()` | `() => void` | Stop the watcher |
+| `watcher.isRunning` | `boolean` (getter) | Whether the watcher is active |
+
+```typescript
+import { startWatch, getText } from '@crosscopy/clipboard'
 
-A clipboard listener will be added soon for monitoring clipboard changes and get notified when the clipboard content changes.
+const watcher = startWatch(async () => {
+  console.log('changed:', await getText())
+})
+
+console.log(watcher.isRunning) // true
+
+// Stop when done
+watcher.stop()
+console.log(watcher.isRunning) // false
+```
+
+The watcher runs on a background thread using native clipboard change events — there is no polling from JavaScript. Call `stop()` to clean up.
+
+## Platform Support
+
+| Platform | Architectures |
+|---|---|
+| macOS | x64, arm64 (Apple Silicon), universal |
+| Windows | x64, arm64 |
+| Linux | x64 (glibc) |
+
+## Acknowledgements
+
+- [ChurchTao/clipboard-rs](https://github.com/ChurchTao/clipboard-rs) provides the native clipboard support across Linux, Windows, and macOS.
+- [napi.rs](https://napi.rs/) bridges the Rust implementation to Node.js.
 
 ## Publish
 
-Everything is done with GitHub Action.
+Everything is done with GitHub Actions.
 
-Run `npm version patch` to bump the version.
-Then `git push --follow-tags` to push the changes and tags to GitHub. GitHub Action will automatically build and publish.
+Run `npm version patch` to bump the version, then `git push --follow-tags`. GitHub Actions will build and publish automatically.
+
+```bash
+npm version patch
+git push --follow-tags
+```

package/README.zh-CN.md

@@ -0,0 +1,205 @@
+# Clipboard
+
+[![NPM Version](https://img.shields.io/npm/v/@crosscopy/clipboard)](https://www.npmjs.com/package/@crosscopy/clipboard)
+[![CI](https://github.com/CrossCopy/clipboard/actions/workflows/CI.yml/badge.svg)](https://github.com/CrossCopy/clipboard/actions/workflows/CI.yml)
+
+**NPM Package**: https://www.npmjs.com/package/@crosscopy/clipboard
+
+**GitHub**: https://github.com/crosscopy/clipboard
+
+跨平台原生剪贴板库，适用于 Node.js。支持读取、写入和监听系统剪贴板，兼容多种数据格式。
+
+### 支持的格式
+
+- 纯文本
+- HTML
+- 富文本 (RTF)
+- 图片 (PNG 二进制 / base64)
+- 文件
+- 任意二进制数据 (自定义格式字符串)
+
+## 安装
+
+```bash
+npm install @crosscopy/clipboard
+# 或
+yarn add @crosscopy/clipboard
+```
+
+## 快速开始
+
+```typescript
+import {
+  getText, setText,
+  hasText, hasImage,
+  getImageBase64,
+  startWatch,
+} from '@crosscopy/clipboard'
+
+// 读写文本
+await setText('hello world')
+console.log(await getText()) // "hello world"
+
+// 检查剪贴板内容类型
+console.log(hasText())  // true
+console.log(hasImage()) // false
+
+// 监听剪贴板变化
+const watcher = startWatch(() => {
+  console.log('剪贴板内容已变化！')
+})
+// ... 之后停止监听
+watcher.stop()
+```
+
+## API
+
+完整的类型声明请参阅 [`index.d.ts`](./index.d.ts)。
+
+### 纯文本
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `hasText` | `() => boolean` | 检查剪贴板是否包含文本 |
+| `getText` | `() => Promise<string>` | 从剪贴板读取文本 |
+| `setText` | `(text: string) => Promise<void>` | 将文本写入剪贴板 |
+
+```typescript
+import { hasText, getText, setText } from '@crosscopy/clipboard'
+
+await setText('已复制！')
+if (hasText()) {
+  console.log(await getText())
+}
+```
+
+### HTML
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `hasHtml` | `() => boolean` | 检查剪贴板是否包含 HTML |
+| `getHtml` | `() => Promise<string>` | 从剪贴板读取 HTML 字符串 |
+| `setHtml` | `(html: string) => Promise<void>` | 将 HTML 字符串写入剪贴板 |
+
+```typescript
+import { setHtml, getHtml } from '@crosscopy/clipboard'
+
+await setHtml('<b>粗体</b>')
+console.log(await getHtml())
+```
+
+### 富文本 (RTF)
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `hasRtf` | `() => boolean` | 检查剪贴板是否包含 RTF |
+| `getRtf` | `() => Promise<string>` | 从剪贴板读取 RTF 字符串 |
+| `setRtf` | `(rtf: string) => Promise<void>` | 将 RTF 字符串写入剪贴板 |
+
+### 图片
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `hasImage` | `() => boolean` | 检查剪贴板是否包含图片 |
+| `getImageBinary` | `() => Promise<Array<number>>` | 以 PNG 字节数组形式读取图片 |
+| `getImageBase64` | `() => Promise<string>` | 以 base64 编码的 PNG 形式读取图片 |
+| `setImageBinary` | `(imageBytes: Array<number>) => Promise<void>` | 将 PNG 字节数组写入剪贴板 |
+| `setImageBase64` | `(base64Str: string) => Promise<void>` | 将 base64 编码的 PNG 写入剪贴板 |
+
+```typescript
+import { hasImage, getImageBase64, setImageBinary } from '@crosscopy/clipboard'
+import { readFileSync } from 'fs'
+
+// 将 PNG 文件写入剪贴板
+const png = readFileSync('screenshot.png')
+await setImageBinary(Array.from(png))
+
+// 以 base64 形式读取
+if (hasImage()) {
+  const b64 = await getImageBase64()
+  console.log(`data:image/png;base64,${b64}`)
+}
+```
+
+### 文件
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `hasFiles` | `() => boolean` | 检查剪贴板是否包含文件引用 |
+| `getFiles` | `() => Promise<Array<string>>` | 从剪贴板读取文件路径列表 |
+| `setFiles` | `(files: Array<string>) => Promise<void>` | 将文件路径列表写入剪贴板 |
+
+```typescript
+import { hasFiles, getFiles } from '@crosscopy/clipboard'
+
+if (hasFiles()) {
+  const paths = await getFiles()
+  console.log(paths) // ["/Users/you/file.txt", ...]
+}
+```
+
+### Buffer (自定义格式)
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `getBuffer` | `(format: string) => Promise<Array<number>>` | 按指定格式读取原始字节 |
+| `setBuffer` | `(format: string, buffer: Array<number>) => Promise<void>` | 按指定格式写入原始字节 |
+
+```typescript
+import { setBuffer, getBuffer } from '@crosscopy/clipboard'
+
+await setBuffer('com.myapp.custom', [0x01, 0x02, 0x03])
+const data = await getBuffer('com.myapp.custom')
+```
+
+### 工具函数
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `availableFormats` | `() => Array<string>` | 列出剪贴板中当前所有的数据格式 |
+| `clear` | `() => Promise<void>` | 清空剪贴板 |
+
+### 剪贴板监听
+
+使用操作系统原生通知机制监听剪贴板变化。
+
+| 函数 / 方法 | 签名 | 说明 |
+|---|---|---|
+| `startWatch` | `(callback: () => void) => ClipboardWatcherJs` | 开始监听，返回监听句柄 |
+| `watcher.stop()` | `() => void` | 停止监听 |
+| `watcher.isRunning` | `boolean` (getter) | 监听器是否正在运行 |
+
+```typescript
+import { startWatch, getText } from '@crosscopy/clipboard'
+
+const watcher = startWatch(async () => {
+  console.log('剪贴板已变化:', await getText())
+})
+
+console.log(watcher.isRunning) // true
+
+// 不再需要时停止监听
+watcher.stop()
+console.log(watcher.isRunning) // false
+```
+
+监听器在后台线程中运行，使用操作系统原生的剪贴板变化事件，JavaScript 侧无需轮询。使用完毕后调用 `stop()` 释放资源。
+
+## 平台支持
+
+| 平台 | 架构 |
+|---|---|
+| macOS | x64, arm64 (Apple Silicon), universal |
+| Windows | x64, arm64 |
+| Linux | x64 (glibc) |
+
+## 致谢
+
+- [ChurchTao/clipboard-rs](https://github.com/ChurchTao/clipboard-rs) 提供了跨 Linux、Windows 和 macOS 的原生剪贴板支持。
+- [napi.rs](https://napi.rs/) 将 Rust 实现桥接到 Node.js。
+
+## 发布
+
+所有构建和发布流程由 GitHub Actions 完成。
+
+执行 `npm version patch` 升级版本号，然后 `git push --follow-tags` 推送到 GitHub，GitHub Actions 会自动构建并发布。

package/index.d.ts

@@ -1,23 +1,55 @@
-/* tslint:disable */
+/* auto-generated by NAPI-RS */
 /* eslint-disable */
+export declare class ClipboardWatcherJs {
+  stop(): void
+  get isRunning(): boolean
+}
 
-/* auto-generated by NAPI-RS */
+export declare function availableFormats(): Array<string>
+
+export declare function clear(): Promise<void>
+
+export declare function getBuffer(format: string): Promise<Array<number>>
+
+export declare function getFiles(): Promise<Array<string>>
+
+export declare function getHtml(): Promise<string>
+
+export declare function getImageBase64(): Promise<string>
+
+export declare function getImageBinary(): Promise<Array<number>>
+
+export declare function getRtf(): Promise<string>
+
+export declare function getText(): Promise<string>
+
+export declare function hasFiles(): boolean
+
+export declare function hasHtml(): boolean
+
+export declare function hasImage(): boolean
+
+export declare function hasRtf(): boolean
+
+export declare function hasText(): boolean
+
+export declare function setBuffer(format: string, buffer: Array<number>): Promise<void>
+
+export declare function setFiles(files: Array<string>): Promise<void>
+
+export declare function setHtml(html: string): Promise<void>
+
+export declare function setImageBase64(base64Str: string): Promise<void>
+
+export declare function setImageBinary(imageBytes: Array<number>): Promise<void>
+
+export declare function setRtf(rtf: string): Promise<void>
+
+export declare function setText(text: string): Promise<void>
 
-export function availableFormats(): Array<string>
-export function getText(): Promise<string>
-export function setText(text: string): Promise<void>
-export function hasText(): boolean
-export function getImageBinary(): Promise<Array<number>>
-export function getImageBase64(): Promise<string>
-export function setImageBinary(imageBytes: Array<number>): Promise<void>
-export function setImageBase64(base64Str: string): Promise<void>
-export function hasImage(): boolean
-export function getHtml(): Promise<string>
-export function setHtml(html: string): Promise<void>
-export function hasHtml(): boolean
-export function getRtf(): Promise<string>
-export function setRtf(rtf: string): Promise<void>
-export function hasRtf(): boolean
-export function clear(): Promise<void>
-export function watch(): void
-export function callThreadsafeFunction(callback: (...args: any[]) => any): void
+/**
+ * Start watching the clipboard for changes.
+ * The callback is invoked whenever the clipboard content changes.
+ * Returns a `ClipboardWatcherJs` handle that can stop the watcher.
+ */
+export declare function startWatch(callback: () => void): ClipboardWatcherJs