tickdb-ts 0.0.0-stage → 0.3.0

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/** manifest FileEntry 字段与线上 JSON 完全一致（snake_case）。 */
+export interface FileEntry {
+    path: string;
+    sha256: string;
+    size: number;
+    row_count: number;
+    symbol: string;
+    cycle: string;
+    ts_min: string;
+    ts_max: string;
+    year?: number;
+    symbols_count?: number;
+    /** v1.2：文件已冻结上云（内容永不再变，可从镜像下载）。 */
+    frozen?: boolean;
+}
+/** 支持的 manifest 版本字面量（parseManifest 收窄到这个联合；新增版本
+ * 时同步 SUPPORTED_VERSIONS 与 sync.ts 的版本门判定）。 */
+export type ManifestVersion = 'v1' | 'v1.1' | 'v1.2' | 'v1.3' | 'v1.4';
+export interface Manifest {
+    version: ManifestVersion;
+    schema: string;
+    generatedAt: string;
+    files: FileEntry[];
+    /** v1.2：对象存储公开基底 URL（未启用 mirror 时缺省）。 */
+    mirror_base_url?: string;
+    /** v1.3：服务端 compacted 文件 (symbol, ts) 互斥（重分区完成）。 */
+    disjoint?: boolean;
+}
+export interface InitOptions {
+    dataDir?: string;
+    token?: string;
+    serverUrl?: string;
+    autoSync?: boolean;
+    syncIntervalSecs?: number;
+    downloadConcurrency?: number;
+}
+export interface SyncReport {
+    notModified: boolean;
+    filesTotal: number;
+    filesFetched: number;
+    filesUnchanged: number;
+    rowsUpserted: number;
+    staleDeleted: number;
+    mirrorFetched: number;
+    mirrorFallbacks: number;
+    errors: string[];
+}
+export interface SyncStatus {
+    running: boolean;
+    startedAt: number;
+    finishedAt: number;
+    filesTotal: number;
+    filesFetched: number;
+    filesUnchanged: number;
+    rowsUpserted: number;
+    staleDeleted: number;
+    errorsCount: number;
+    daemonIntervalSecs: number;
+    daemonRunning: boolean;
+    lastError: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.d.ts

@@ -0,0 +1,14 @@
+/** 固定并发工作池：items 逐个领取，任何 fn 抛错由 fn 自身捕获（调用方负责 per-item try/catch）。 */
+export declare function runPool<T>(items: readonly T[], limit: number, fn: (item: T) => Promise<void>): Promise<void>;
+export declare function parseCycleYear(path: string): {
+    cycle: string;
+    year: number;
+};
+/** extra/ 前缀 = 聚合数据集文件（manifest v1.4）：恒 direct 分流——
+ * 落盘 + view 直读，不进 kline upsert / 按 cycle-year 删行逻辑
+ * （对齐 Rust is_extra_file）。 */
+export declare function isExtraFile(p: string): boolean;
+export declare function yearBounds(year: number): [string, string];
+export declare function expandHome(p: string): string;
+export declare const nowSec: () => number;
+export declare const sleep: (ms: number) => Promise<void>;

package/dist/util.js

@@ -0,0 +1,38 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 固定并发工作池：items 逐个领取，任何 fn 抛错由 fn 自身捕获（调用方负责 per-item try/catch）。 */
+export async function runPool(items, limit, fn) {
+    let i = 0;
+    const n = Math.max(1, Math.min(limit, items.length));
+    const workers = Array.from({ length: n }, async () => {
+        while (i < items.length) {
+            const idx = i++;
+            await fn(items[idx]);
+        }
+    });
+    await Promise.all(workers);
+}
+export function parseCycleYear(path) {
+    const m = /cycle=([^/]+)\/year=(\d{4})(?:-month=\d{2})?\.parquet$/.exec(path);
+    if (!m)
+        throw new Error(`cannot parse cycle/year from manifest path: ${path}`);
+    return { cycle: m[1], year: Number(m[2]) };
+}
+/** extra/ 前缀 = 聚合数据集文件（manifest v1.4）：恒 direct 分流——
+ * 落盘 + view 直读，不进 kline upsert / 按 cycle-year 删行逻辑
+ * （对齐 Rust is_extra_file）。 */
+export function isExtraFile(p) {
+    return p.startsWith('extra/');
+}
+export function yearBounds(year) {
+    return [`${year}-01-01 00:00:00`, `${year}-12-31 23:59:59`];
+}
+export function expandHome(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+export const nowSec = () => Math.floor(Date.now() / 1000);
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "tickdb-ts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "offline-first TypeScript client for tickdb (A-share market data): manifest sync + local DuckDB",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" } },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chuanlei-coding/growinpublic.git",
+    "directory": "tickdb/clients/tickdb-ts"
+  },
+  "license": "MIT",
+  "dependencies": { "@duckdb/node-api": "^2.0.0-r.1" },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}