pure-js-db 0.0.0-stage → 2.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (541) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +747 -3
  3. package/bindings/java/pom.xml +18 -0
  4. package/bindings/java/src/main/java/purejsdb/PureJsDBClient.java +146 -0
  5. package/bindings/java/src/main/java/purejsdb/TransactionClient.java +65 -0
  6. package/bindings/java/src/test/java/TestClient.java +68 -0
  7. package/bindings/orm/sequelize-adapter.js +1236 -0
  8. package/bindings/python/purejsdb/client.py +81 -0
  9. package/bindings/python/setup.py +9 -0
  10. package/bindings/python/test_client.py +63 -0
  11. package/config/datagrip-config.md +206 -0
  12. package/config/grafana-dashboard.json +1510 -0
  13. package/config/production.config.js +126 -0
  14. package/config/prometheus-scrape.yml +39 -0
  15. package/native/index.node +0 -0
  16. package/package.json +205 -6
  17. package/scripts/mcp-server.mjs +208 -0
  18. package/src/adapter/dialect-adapter.js +179 -0
  19. package/src/adapter/oracle-adapter.js +191 -0
  20. package/src/ai/ai-service.js +713 -0
  21. package/src/ai/rag-pipeline.js +160 -0
  22. package/src/alerting/alert-manager.js +622 -0
  23. package/src/alerting/index.js +10 -0
  24. package/src/arrow/arrow-ipc.js +973 -0
  25. package/src/arrow/flatbuffer.js +521 -0
  26. package/src/arrow/index.js +261 -0
  27. package/src/arrow/parquet.js +1525 -0
  28. package/src/audit/audit-log.js +1345 -0
  29. package/src/audit/audit-report.js +571 -0
  30. package/src/audit/index.js +6 -0
  31. package/src/backpressure/backpressure-controller.js +262 -0
  32. package/src/backpressure/index.js +6 -0
  33. package/src/backpressure/write-rate-limiter.js +243 -0
  34. package/src/backup/backup-manager.js +416 -0
  35. package/src/backup/index.js +8 -0
  36. package/src/backup/logical-backup.js +228 -0
  37. package/src/backup/snapshot.js +111 -0
  38. package/src/backup/toolkit.js +410 -0
  39. package/src/bindings/orm/prisma-adapter.js +571 -0
  40. package/src/bindings/orm/typeorm-adapter.js +477 -0
  41. package/src/cache/adaptive-cache-size.js +288 -0
  42. package/src/cache/adaptive-ttl.js +139 -0
  43. package/src/cache/cache-adapter.js +304 -0
  44. package/src/cache/circuit-breaker.js +294 -0
  45. package/src/cache/index.js +31 -0
  46. package/src/cache/lru-cache.js +353 -0
  47. package/src/cache/redis-adapter.js +391 -0
  48. package/src/cache/resilient-adapter.js +391 -0
  49. package/src/cache/result-cache.js +493 -0
  50. package/src/cache/semantic-cache.js +339 -0
  51. package/src/cdc/cdc-engine.js +1061 -0
  52. package/src/cdc/cdc-handlers.js +289 -0
  53. package/src/cdc/ddl-capture.js +330 -0
  54. package/src/cdc/debezium-adapter.js +366 -0
  55. package/src/cdc/schema-history.js +414 -0
  56. package/src/changelog/changelog-buffer.js +881 -0
  57. package/src/changelog/changelog-wal.js +299 -0
  58. package/src/changelog/linear-regression-predictor.js +186 -0
  59. package/src/changelog/predictive-growth.js +348 -0
  60. package/src/changelog/seasonal-predictor.js +450 -0
  61. package/src/changelog/write-rate-sampler.js +141 -0
  62. package/src/cli/dump-command.js +944 -0
  63. package/src/cli/interactive.js +188 -0
  64. package/src/cli/migrate-command.js +252 -0
  65. package/src/cli.js +533 -0
  66. package/src/cluster/failover.js +477 -0
  67. package/src/cluster/index.js +19 -0
  68. package/src/cluster/persistent-state.js +203 -0
  69. package/src/cluster/public-api.js +58 -0
  70. package/src/cluster/raft-http-transport.js +280 -0
  71. package/src/cluster/raft-log.js +313 -0
  72. package/src/cluster/raft.js +912 -0
  73. package/src/cluster/snapshot-persistence.js +131 -0
  74. package/src/concurrency/async-mutex.js +365 -0
  75. package/src/concurrency/circuit-breaker.js +326 -0
  76. package/src/concurrency/connection-pool.js +409 -0
  77. package/src/concurrency/connection-session.js +498 -0
  78. package/src/concurrency/index.js +29 -0
  79. package/src/concurrency/lock-manager.js +363 -0
  80. package/src/concurrency/lockfree-executor.js +322 -0
  81. package/src/concurrency/lockfree-manager.js +570 -0
  82. package/src/concurrency/mvcc.js +499 -0
  83. package/src/concurrency/occ-hot-row.js +726 -0
  84. package/src/concurrency/query-degradation.js +380 -0
  85. package/src/concurrency/query-isolation.js +374 -0
  86. package/src/concurrency/shared-memory-pool.js +459 -0
  87. package/src/concurrency/snapshot-buffer.js +461 -0
  88. package/src/concurrency/transaction-context.js +193 -0
  89. package/src/copy/copy-stream.js +643 -0
  90. package/src/copy/index.js +5 -0
  91. package/src/core/database.js +1947 -0
  92. package/src/core/index.js +13 -0
  93. package/src/daemon/compact-daemon.js +535 -0
  94. package/src/daemon/index.js +14 -0
  95. package/src/daemon/soa-daemon-integration.js +333 -0
  96. package/src/ddl/online-ddl.js +348 -0
  97. package/src/disruptor/disruptor.js +348 -0
  98. package/src/disruptor/event-bus.js +238 -0
  99. package/src/disruptor/event-pool.js +62 -0
  100. package/src/disruptor/index.js +31 -0
  101. package/src/disruptor/ring-buffer.js +150 -0
  102. package/src/disruptor/sequence.js +88 -0
  103. package/src/disruptor/wait-strategy.js +160 -0
  104. package/src/engine/public-api.js +210 -0
  105. package/src/executor/asof-join-executor.js +265 -0
  106. package/src/executor/bitmap-filter.js +1382 -0
  107. package/src/executor/compiled-expression.js +472 -0
  108. package/src/executor/compiled-predicate.js +458 -0
  109. package/src/executor/constraint-executor.js +577 -0
  110. package/src/executor/copy-executor.js +210 -0
  111. package/src/executor/cte/recursive-cte.js +89 -0
  112. package/src/executor/cte-executor.js +501 -0
  113. package/src/executor/cursor-executor.js +216 -0
  114. package/src/executor/database.js +41 -0
  115. package/src/executor/ddl-executor.js +3531 -0
  116. package/src/executor/dml-executor.js +3557 -0
  117. package/src/executor/executor-worker.js +331 -0
  118. package/src/executor/executor.js +10889 -0
  119. package/src/executor/explain-analyzer.js +422 -0
  120. package/src/executor/explain-executor.js +324 -0
  121. package/src/executor/expression.js +4972 -0
  122. package/src/executor/foreign-key-executor.js +691 -0
  123. package/src/executor/graph-table-executor.js +451 -0
  124. package/src/executor/grouping-executor.js +251 -0
  125. package/src/executor/hotpath.js +232 -0
  126. package/src/executor/hybrid-search-executor.js +326 -0
  127. package/src/executor/incremental-live-query.js +866 -0
  128. package/src/executor/index-maintenance-executor.js +731 -0
  129. package/src/executor/index.js +16 -0
  130. package/src/executor/info-schema-executor.js +123 -0
  131. package/src/executor/join/lateral-join.js +64 -0
  132. package/src/executor/join-executor.js +530 -0
  133. package/src/executor/lineage-executor.js +85 -0
  134. package/src/executor/live-query-manager.js +350 -0
  135. package/src/executor/loop-unroll.js +539 -0
  136. package/src/executor/match-recognize-executor.js +918 -0
  137. package/src/executor/multi-stream-wal.js +140 -0
  138. package/src/executor/nl2sql-executor.js +309 -0
  139. package/src/executor/parallel-dml.js +258 -0
  140. package/src/executor/pivot-executor.js +458 -0
  141. package/src/executor/pragma-executor.js +661 -0
  142. package/src/executor/select-executor.js +857 -0
  143. package/src/executor/sequence.js +139 -0
  144. package/src/executor/sql-reconstructor.js +296 -0
  145. package/src/executor/subquery-cache.js +186 -0
  146. package/src/executor/subquery-executor.js +1390 -0
  147. package/src/executor/system-catalog.js +731 -0
  148. package/src/executor/table-function-executor.js +656 -0
  149. package/src/executor/topn.js +103 -0
  150. package/src/executor/transaction-executor.js +926 -0
  151. package/src/executor/trigger-executor.js +441 -0
  152. package/src/executor/v8-turbofan-optimizer.js +363 -0
  153. package/src/executor/vector-acceleration.js +456 -0
  154. package/src/executor/vector-executor.js +847 -0
  155. package/src/executor/vectorized-columnar-engine.js +1130 -0
  156. package/src/executor/vectorized-executor-v2.js +993 -0
  157. package/src/executor/view-executor.js +149 -0
  158. package/src/executor/wal.js +1945 -0
  159. package/src/executor/wasm-simd-engine.js +929 -0
  160. package/src/executor/window-functions.js +894 -0
  161. package/src/fdw/fdw-manager.js +642 -0
  162. package/src/fdw/index.js +5 -0
  163. package/src/geo/geometry.js +447 -0
  164. package/src/geo/index.js +16 -0
  165. package/src/geo/spatial-functions.js +1241 -0
  166. package/src/graph/graph-helper.js +243 -0
  167. package/src/graph/pgq-matcher.js +2545 -0
  168. package/src/graph/property-graph.js +123 -0
  169. package/src/graphql-bridge.js +881 -0
  170. package/src/hotspot/access-tracker.js +188 -0
  171. package/src/hotspot/hotspot-detector.js +140 -0
  172. package/src/hotspot/hotspot-prefetcher.js +210 -0
  173. package/src/hotspot/index.js +7 -0
  174. package/src/http-api.js +1182 -0
  175. package/src/http-server/handlers/audit.js +224 -0
  176. package/src/http-server/handlers/changes-feed.js +261 -0
  177. package/src/http-server/handlers/management.js +464 -0
  178. package/src/http-server/handlers/query.js +573 -0
  179. package/src/http-server/handlers/transaction.js +251 -0
  180. package/src/http-server/index.js +89 -0
  181. package/src/http-server/openapi.js +656 -0
  182. package/src/http-server/router.js +120 -0
  183. package/src/http-server/server.js +1915 -0
  184. package/src/http-server/tls.js +126 -0
  185. package/src/http-server/ws-server.js +873 -0
  186. package/src/index/adaptive-hash-index.js +176 -0
  187. package/src/index/bitmap-index.js +429 -0
  188. package/src/index/brin-index.js +246 -0
  189. package/src/index/btree-index.js +428 -0
  190. package/src/index/btree.js +690 -0
  191. package/src/index/diskann-index.js +1903 -0
  192. package/src/index/fulltext/fulltext-index.js +66 -0
  193. package/src/index/fulltext/index.js +3 -0
  194. package/src/index/fulltext/inverted-index.js +197 -0
  195. package/src/index/fulltext/tokenizer.js +154 -0
  196. package/src/index/fulltext.js +287 -0
  197. package/src/index/gin-index.js +316 -0
  198. package/src/index/gist-index.js +463 -0
  199. package/src/index/gist-ops.js +325 -0
  200. package/src/index/graph-compressor.js +505 -0
  201. package/src/index/hash-index.js +180 -0
  202. package/src/index/hnsw-index.js +1232 -0
  203. package/src/index/hnsw-pq-index.js +1147 -0
  204. package/src/index/index-auto-tuner.js +1341 -0
  205. package/src/index/index-interface.js +364 -0
  206. package/src/index/index-selector.js +523 -0
  207. package/src/index/index.js +28 -0
  208. package/src/index/ivfpqsq-index.js +1163 -0
  209. package/src/index/offheap-btree-index.js +395 -0
  210. package/src/index/offheap-btree.js +748 -0
  211. package/src/index/product-quantizer.js +1447 -0
  212. package/src/index/robin-hood-hash-index.js +384 -0
  213. package/src/index/rtree-index.js +982 -0
  214. package/src/index/scalar-quantizer.js +411 -0
  215. package/src/index/semantic-index.js +283 -0
  216. package/src/index/string-interner.js +238 -0
  217. package/src/index/timestamp-index-advisor.js +491 -0
  218. package/src/index/timestamp-index-compressed.js +800 -0
  219. package/src/index/timestamp-index-compressor.js +547 -0
  220. package/src/index/timestamp-index.js +579 -0
  221. package/src/index/vector-index-serializer.js +499 -0
  222. package/src/index/vector-index-stats.js +450 -0
  223. package/src/index/vector-index.js +615 -0
  224. package/src/index-v3.js +27 -0
  225. package/src/index.js +33 -0
  226. package/src/internal/public-api.js +198 -0
  227. package/src/lineage/column-lineage.js +393 -0
  228. package/src/lineage/index.js +11 -0
  229. package/src/lineage/lineage-store.js +701 -0
  230. package/src/lineage/table-lineage.js +68 -0
  231. package/src/mcp/index.js +176 -0
  232. package/src/mcp/mcp-server.js +334 -0
  233. package/src/mcp/protocol.js +195 -0
  234. package/src/mcp/tools/backup-restore.js +131 -0
  235. package/src/mcp/tools/cdc-tools.js +201 -0
  236. package/src/mcp/tools/describe-table.js +100 -0
  237. package/src/mcp/tools/execute-sql.js +210 -0
  238. package/src/mcp/tools/explain-query.js +75 -0
  239. package/src/mcp/tools/index-management.js +191 -0
  240. package/src/mcp/tools/lineage.js +64 -0
  241. package/src/mcp/tools/list-tables.js +46 -0
  242. package/src/mcp/tools/monitoring.js +195 -0
  243. package/src/mcp/tools/schema-management.js +229 -0
  244. package/src/mcp/tools/text-to-sql.js +84 -0
  245. package/src/mcp/tools/transaction-management.js +191 -0
  246. package/src/mcp/tools/vector-search.js +101 -0
  247. package/src/mcp/transport/http.js +352 -0
  248. package/src/mcp/transport/stdio.js +117 -0
  249. package/src/memory/memory-manager.js +437 -0
  250. package/src/migration/migrator.js +389 -0
  251. package/src/monitor/index.js +36 -0
  252. package/src/monitor/metrics-exporter.js +517 -0
  253. package/src/monitor/monitor.js +385 -0
  254. package/src/monitor/performance-monitor.js +204 -0
  255. package/src/monitor/soa-monitor.js +628 -0
  256. package/src/multitenant/index.js +1 -0
  257. package/src/multitenant/tenant-manager.js +238 -0
  258. package/src/native/native-acceleration.js +3493 -0
  259. package/src/optimizer/adaptive-optimizer.js +666 -0
  260. package/src/optimizer/cse.js +383 -0
  261. package/src/optimizer/decorrelator.js +958 -0
  262. package/src/optimizer/derived-table-eliminator.js +367 -0
  263. package/src/optimizer/explain-visualizer.js +266 -0
  264. package/src/optimizer/histogram.js +290 -0
  265. package/src/optimizer/index.js +78 -0
  266. package/src/optimizer/jit-compiler.js +1200 -0
  267. package/src/optimizer/join-order-optimizer.js +717 -0
  268. package/src/optimizer/limit-pushdown.js +70 -0
  269. package/src/optimizer/optimized-plan.js +54 -0
  270. package/src/optimizer/optimizer-rule.js +295 -0
  271. package/src/optimizer/optimizer.js +1515 -0
  272. package/src/optimizer/pipeline.js +263 -0
  273. package/src/optimizer/predicate-pushdown.js +599 -0
  274. package/src/optimizer/query-plan-cache.js +275 -0
  275. package/src/optimizer/rule-adapters.js +343 -0
  276. package/src/optimizer/subquery-flattener.js +689 -0
  277. package/src/optimizer/timestamp-query-rewriter.js +498 -0
  278. package/src/orm/collection.js +160 -0
  279. package/src/orm/errors.js +76 -0
  280. package/src/orm/hooks.js +184 -0
  281. package/src/orm/index.js +93 -0
  282. package/src/orm/mixins/soft-delete.js +271 -0
  283. package/src/orm/model.js +951 -0
  284. package/src/orm/query-builder.js +681 -0
  285. package/src/orm/relations.js +303 -0
  286. package/src/orm/schema.js +443 -0
  287. package/src/orm/seeder.js +350 -0
  288. package/src/parallel/dml-pushdown-executor.js +430 -0
  289. package/src/parallel/dml-worker.js +151 -0
  290. package/src/parallel/morsel-queue.js +358 -0
  291. package/src/parallel/parallel-executor.js +277 -0
  292. package/src/parallel/pipeline-executor.js +423 -0
  293. package/src/parallel/shared-cache.js +206 -0
  294. package/src/parser/ast.js +3853 -0
  295. package/src/parser/parser.js +7909 -0
  296. package/src/parser/tokenizer.js +542 -0
  297. package/src/query/relation-preloader.js +327 -0
  298. package/src/replication/index.js +15 -0
  299. package/src/replication/lag-monitor.js +163 -0
  300. package/src/replication/master.js +117 -0
  301. package/src/replication/multi-master.js +495 -0
  302. package/src/replication/read-replica.js +490 -0
  303. package/src/replication/replica.js +395 -0
  304. package/src/replication/replication-http-transport.js +421 -0
  305. package/src/replication/wal-standby.js +334 -0
  306. package/src/runtime/index.js +4 -0
  307. package/src/runtime/plpgsql-interpreter.js +766 -0
  308. package/src/runtime/plpgsql-parser.js +852 -0
  309. package/src/runtime/stored-procedure.js +149 -0
  310. package/src/runtime/udf.js +194 -0
  311. package/src/schema/dsl-parser.js +896 -0
  312. package/src/schema/index.js +113 -0
  313. package/src/schema/introspector.js +246 -0
  314. package/src/schema/pg-migrator.js +599 -0
  315. package/src/schema/schema-differ.js +504 -0
  316. package/src/schema/schema-versioning.js +426 -0
  317. package/src/schema/type-generator.js +537 -0
  318. package/src/sdk/README.md +277 -0
  319. package/src/sdk/go/README.md +19 -0
  320. package/src/sdk/go/go.mod +3 -0
  321. package/src/sdk/go/pureclient/client.go +663 -0
  322. package/src/sdk/go/pureclient/client_test.go +413 -0
  323. package/src/sdk/java/README.md +19 -0
  324. package/src/sdk/java/pom.xml +87 -0
  325. package/src/sdk/java/pureclient/JsonUtil.java +366 -0
  326. package/src/sdk/java/pureclient/PureClient.java +835 -0
  327. package/src/sdk/java/pureclient/PureClientTest.java +570 -0
  328. package/src/sdk/java/pureclient/PureError.java +158 -0
  329. package/src/sdk/java/pureclient/Transaction.java +242 -0
  330. package/src/sdk/javascript/README.md +19 -0
  331. package/src/sdk/javascript/cdc.js +230 -0
  332. package/src/sdk/javascript/client.js +420 -0
  333. package/src/sdk/javascript/errors.js +66 -0
  334. package/src/sdk/javascript/index.js +35 -0
  335. package/src/sdk/javascript/pool.js +199 -0
  336. package/src/sdk/javascript/transaction.js +114 -0
  337. package/src/sdk/php/README.md +19 -0
  338. package/src/sdk/php/composer.json +30 -0
  339. package/src/sdk/php/src/PureClient.php +550 -0
  340. package/src/sdk/php/src/PureError.php +130 -0
  341. package/src/sdk/php/src/Transaction.php +172 -0
  342. package/src/sdk/public-api.js +16 -0
  343. package/src/sdk/python/README.md +19 -0
  344. package/src/sdk/python/pure_client.py +388 -0
  345. package/src/sdk/react-native/README.md +161 -0
  346. package/src/sdk/react-native/async-storage-adapter.js +147 -0
  347. package/src/sdk/react-native/embedded/embedded-client.js +266 -0
  348. package/src/sdk/react-native/embedded/hermes-jsi-bridge.js +207 -0
  349. package/src/sdk/react-native/embedded/sqlite-kv-adapter.js +345 -0
  350. package/src/sdk/react-native/expo-file-adapter.js +315 -0
  351. package/src/sdk/react-native/index.js +52 -0
  352. package/src/sdk/react-native/mobile-client.js +759 -0
  353. package/src/sdk/react-native/sync-manager.js +455 -0
  354. package/src/sdk/react-native/vector-search.js +322 -0
  355. package/src/sdk/rust/CHANGELOG.md +104 -0
  356. package/src/sdk/rust/Cargo.toml +35 -0
  357. package/src/sdk/rust/LICENSE +21 -0
  358. package/src/sdk/rust/PUBLISHING.md +202 -0
  359. package/src/sdk/rust/README.md +471 -0
  360. package/src/sdk/rust/RELEASE-CHECKLIST.md +340 -0
  361. package/src/sdk/rust/examples/basic_usage.rs +181 -0
  362. package/src/sdk/rust/scripts/publish.sh +233 -0
  363. package/src/sdk/rust/src/client.rs +481 -0
  364. package/src/sdk/rust/src/error.rs +95 -0
  365. package/src/sdk/rust/src/index/hnswpq.rs +626 -0
  366. package/src/sdk/rust/src/index/mod.rs +7 -0
  367. package/src/sdk/rust/src/lib.rs +66 -0
  368. package/src/sdk/rust/src/models.rs +198 -0
  369. package/src/sdk/rust/src/transaction.rs +123 -0
  370. package/src/sdk/rust/tests/concurrent_vector_search.rs +534 -0
  371. package/src/sdk/wechat/README.md +19 -0
  372. package/src/sdk/wechat/index.js +42 -0
  373. package/src/sdk/wechat/pure-js-db.js +105 -0
  374. package/src/sdk/wechat/stubs/empty.js +85 -0
  375. package/src/sdk/wechat/wx-database.js +225 -0
  376. package/src/sdk/wechat/wx-lite.js +191 -0
  377. package/src/sdk/wechat/wx-sqlite-adapter.js +655 -0
  378. package/src/sdk/wechat/wx-sqlite-database.js +146 -0
  379. package/src/sdk/wechat/wx-storage-adapter.js +609 -0
  380. package/src/security/api-key.js +215 -0
  381. package/src/security/auth.js +179 -0
  382. package/src/security/column-encryption-optimized.js +352 -0
  383. package/src/security/column-encryption.js +330 -0
  384. package/src/security/crypto-provider.js +345 -0
  385. package/src/security/data-masking.js +370 -0
  386. package/src/security/field-encryption.js +238 -0
  387. package/src/security/index.js +41 -0
  388. package/src/security/jwt.js +202 -0
  389. package/src/security/rbac.js +702 -0
  390. package/src/security/regex-guard.js +277 -0
  391. package/src/security/row-level-security.js +192 -0
  392. package/src/security/secure-erase.js +258 -0
  393. package/src/security/sql-firewall.js +185 -0
  394. package/src/security/sql-injection-detector.js +647 -0
  395. package/src/security/sql-rate-limiter.js +168 -0
  396. package/src/security/ssrf-guard.js +790 -0
  397. package/src/security/timing-safe.js +203 -0
  398. package/src/serializer/codecs.js +1155 -0
  399. package/src/serializer/index.js +13 -0
  400. package/src/serializer/serializer.js +468 -0
  401. package/src/server/public-api.js +14 -0
  402. package/src/server.js +31 -0
  403. package/src/service/log-service.js +593 -0
  404. package/src/sharding/cluster-manager.js +161 -0
  405. package/src/sharding/consistent-hash-ring-optimized.js +421 -0
  406. package/src/sharding/consistent-hash-ring.js +252 -0
  407. package/src/sharding/consistent-hash.js +175 -0
  408. package/src/sharding/distributed-executor.js +120 -0
  409. package/src/sharding/distributed-lock.js +256 -0
  410. package/src/sharding/distributed-transaction.js +262 -0
  411. package/src/sharding/failure-recovery.js +267 -0
  412. package/src/sharding/global-tx-coordinator.js +1299 -0
  413. package/src/sharding/index.js +16 -0
  414. package/src/sharding/parallel-write-coordinator.js +370 -0
  415. package/src/sharding/partition-manager.js +382 -0
  416. package/src/sharding/pushdown-executor.js +1101 -0
  417. package/src/sharding/scatter-gather-executor.js +460 -0
  418. package/src/sharding/shard-executor.js +624 -0
  419. package/src/sharding/shard-manager.js +717 -0
  420. package/src/sharding/three-phase-commit.js +699 -0
  421. package/src/sharding/two-phase-commit.js +1243 -0
  422. package/src/snapshot/historical-reader.js +257 -0
  423. package/src/snapshot/index.js +7 -0
  424. package/src/storage/batch-writer.js +110 -0
  425. package/src/storage/binary-storage-adapter.js +738 -0
  426. package/src/storage/blob-kv-adapter.js +253 -0
  427. package/src/storage/buffer-pool.js +458 -0
  428. package/src/storage/buffered-kv-adapter.js +325 -0
  429. package/src/storage/cold-data-migrator.js +519 -0
  430. package/src/storage/column-compression.js +878 -0
  431. package/src/storage/column-store-table.js +627 -0
  432. package/src/storage/column-store.js +1094 -0
  433. package/src/storage/columnar-file.js +489 -0
  434. package/src/storage/columnar-storage.js +485 -0
  435. package/src/storage/compact-recovery.js +394 -0
  436. package/src/storage/encrypted-kv-adapter.js +271 -0
  437. package/src/storage/file-kv-adapter.js +468 -0
  438. package/src/storage/hybrid-engine.js +1480 -0
  439. package/src/storage/importer.js +125 -0
  440. package/src/storage/in-memory-table-storage.js +291 -0
  441. package/src/storage/index.js +78 -0
  442. package/src/storage/io-thread-pool.js +240 -0
  443. package/src/storage/io-worker.js +42 -0
  444. package/src/storage/kv-adapter.js +322 -0
  445. package/src/storage/lsm/active-table.js +240 -0
  446. package/src/storage/lsm/block-cache.js +64 -0
  447. package/src/storage/lsm/bloom-filter.js +174 -0
  448. package/src/storage/lsm/compactor.js +460 -0
  449. package/src/storage/lsm/database-manager.js +177 -0
  450. package/src/storage/lsm/full-text-search.js +385 -0
  451. package/src/storage/lsm/index.js +14 -0
  452. package/src/storage/lsm/internal-key.js +140 -0
  453. package/src/storage/lsm/lsm-engine.js +798 -0
  454. package/src/storage/lsm/lsm-kv-adapter.js +137 -0
  455. package/src/storage/lsm/memtable.js +628 -0
  456. package/src/storage/lsm/mmap-region.js +289 -0
  457. package/src/storage/lsm/sstable-reader.js +403 -0
  458. package/src/storage/lsm/sstable-repair.js +437 -0
  459. package/src/storage/lsm/sstable-writer.js +202 -0
  460. package/src/storage/lsm/wal.js +800 -0
  461. package/src/storage/offheap-allocator.js +298 -0
  462. package/src/storage/page-checksum.js +221 -0
  463. package/src/storage/page-compression.js +95 -0
  464. package/src/storage/page-store.js +418 -0
  465. package/src/storage/page.js +261 -0
  466. package/src/storage/persisted-db.js +1885 -0
  467. package/src/storage/persisted-table-storage.js +280 -0
  468. package/src/storage/read-ahead.js +95 -0
  469. package/src/storage/shared-storage.js +688 -0
  470. package/src/storage/soa-table-storage.js +418 -0
  471. package/src/storage/storage-engine.js +187 -0
  472. package/src/storage/table-storage.js +215 -0
  473. package/src/storage/tiered-kv-adapter.js +381 -0
  474. package/src/storage/version-history-cleaner.js +888 -0
  475. package/src/studio/index.html +1503 -0
  476. package/src/studio/server.js +204 -0
  477. package/src/sync/change-log.js +144 -0
  478. package/src/sync/index.js +2 -0
  479. package/src/sync/sync-engine.js +428 -0
  480. package/src/sync/sync-handlers.js +196 -0
  481. package/src/test-utils.js +11 -0
  482. package/src/transaction/index.js +8 -0
  483. package/src/transaction/read-uncommitted.js +37 -0
  484. package/src/transaction/repeatable-read.js +380 -0
  485. package/src/transaction/rr-transaction-manager.js +262 -0
  486. package/src/transaction/ru-transaction-manager.js +76 -0
  487. package/src/transaction/serializable.js +205 -0
  488. package/src/transaction/transaction-manager.js +259 -0
  489. package/src/transaction/tx-manager.js +490 -0
  490. package/src/transaction/tx-state.js +43 -0
  491. package/src/tx/bfmark-snapshot.js +193 -0
  492. package/src/tx/row-lock.js +246 -0
  493. package/src/tx/ssi.js +229 -0
  494. package/src/types/datetime.js +621 -0
  495. package/src/types/decimal.js +220 -0
  496. package/src/types/enum-type.js +131 -0
  497. package/src/types/interval.js +565 -0
  498. package/src/types/json-type.js +376 -0
  499. package/src/types/jsonb.js +227 -0
  500. package/src/types/udt.js +180 -0
  501. package/src/utils/batch-processor.js +46 -0
  502. package/src/utils/debug-logger.js +116 -0
  503. package/src/utils/index-helper.js +74 -0
  504. package/src/utils/index.js +9 -0
  505. package/src/utils/join-engine.js +1713 -0
  506. package/src/utils/object-pool.js +610 -0
  507. package/src/utils/query-tracer.js +489 -0
  508. package/src/utils/timeout-util.js +92 -0
  509. package/src/utils/tx-log-persist.js +197 -0
  510. package/src/utils/undo-compress.js +93 -0
  511. package/src/utils/undo-log.js +196 -0
  512. package/src/utils/wal-common.js +138 -0
  513. package/src/vector/adaptive-ef.js +213 -0
  514. package/src/vector/distributed-vector-search.js +542 -0
  515. package/src/vector/federated-vector-search.js +707 -0
  516. package/src/vector/gpu-distance.js +647 -0
  517. package/src/vector/gpu-sq-distance.js +444 -0
  518. package/src/vector/hnsw-acceleration.js +298 -0
  519. package/src/vector/hnsw-profiler.js +341 -0
  520. package/src/vector/index.js +90 -0
  521. package/src/vector/public-api.js +29 -0
  522. package/src/vector/recall-benchmark.js +333 -0
  523. package/src/vector/simd-distance.js +511 -0
  524. package/src/vector/vector-scan.js +646 -0
  525. package/src/vector/wasm-hnsw.js +714 -0
  526. package/src/version/version-chain-manager.js +1277 -0
  527. package/src/version/version-delta-encoder.js +819 -0
  528. package/src/version.js +19 -0
  529. package/src/view/incremental-refresher.js +1015 -0
  530. package/src/view/index.js +12 -0
  531. package/src/view/materialized-view.js +204 -0
  532. package/src/view/view-manager.js +1368 -0
  533. package/src/wasm/bridge.js +79 -0
  534. package/src/worker/query-dispatcher.js +277 -0
  535. package/src/worker/session-worker-pool.js +355 -0
  536. package/src/worker/task-defs.js +330 -0
  537. package/src/worker/task-worker.js +406 -0
  538. package/src/worker/worker-pool.js +651 -0
  539. package/src/xml/xml-support.js +647 -0
  540. package/types/pure-js-db.d.ts +1988 -0
  541. package/types/schema.d.ts +65 -0
package/README.md CHANGED
@@ -1,3 +1,747 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # Pure-JS-DB
2
+
3
+ > **零依赖嵌入式数据库引擎 —— 单文件部署,同时支持向量搜索、MVCC 并发写入、CDC 变更捕获。**
4
+ > 如果你的 Node.js 应用需要 PostgreSQL + Milvus + Debezium 的能力但不想要三个独立服务,这里一个文件就够。
5
+
6
+ > 📌 **当前状态**:v2.53.0,成熟度 **Beta+(工程验证成熟)**。历史版本公告(E26 查询缓存/时间旅行、F1-F10 接线、安全审计加固等)详见 [CHANGELOG.md](CHANGELOG.md) 与 [docs/internal/audit/](docs/internal/audit/) 审计档案。安全模块默认 fail-closed,生产部署必须显式配置认证/RBAC/加密(见 [SECURITY.md](SECURITY.md) §2.2)。
7
+
8
+ ![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)
9
+ ![License](https://img.shields.io/badge/license-MIT-blue)
10
+ ![Version](https://img.shields.io/badge/version-2.53.0-blue)
11
+ ![Tests](https://img.shields.io/badge/tests-826%20files-brightgreen)
12
+ ![LOC](https://img.shields.io/badge/loc-~225k-blue)
13
+ ![Maturity](https://img.shields.io/badge/maturity-Beta%2B%20engineering%20validated-orange)
14
+ ![SDKs](https://img.shields.io/badge/SDKs-52-blueviolet)
15
+ ![Coverage](https://img.shields.io/badge/c8%20coverage-91.72%25%20lines-brightgreen)
16
+ ![Pure JS Core](https://img.shields.io/badge/pure%20JS%20core-100%25-brightgreen)
17
+
18
+ **项目规模**:~224,560 行原生 JavaScript(479 个源文件,零外部依赖),826+ 个测试文件注册于 run-all(2026-10-28 实测 818/818 全绿,需将 node 与 `node_modules/.bin` 加入 PATH),覆盖 SQL 解析器、执行引擎、11 种主流索引、CBO 优化器、LSM/列存/HTAP 混合存储、向量化执行、11 类向量索引(HNSW/IVF/DiskANN/PQ/SQ + SIMD/GPU/Rust 加速)、Raft 共识、分布式分片(scatter-gather 下推)、MCP Server(26 个 LLM 工具,stdio + HTTP/SSE 双传输,可直接运行 `node scripts/mcp-server.mjs`)、CDC + Debezium 兼容、REST + GraphQL + OpenAPI + WebSocket + SSE 五位一体 API 等子系统。
19
+
20
+ > 📊 **覆盖率口径说明**:c8 覆盖率 badge(91.72% lines)为"排除后"数字——按 `package.json` 的 `c8.exclude`,排除了 `src/sdk`、`src/cli`、`src/http-server`、`src/mcp`、`src/wasm`、`src/arrow`、`src/bindings`、`src/fdw`、`src/ai`、`src/studio`、`src/server.js`、`src/http-api.js`、`src/graphql-bridge.js` 等 75 个文件(约占 src 的 16%),按全库口径折算约为 77%。其中 wasm/bindings/fdw/arrow 为可选/外部对接层,但 HTTP/CLI/MCP/SDK 等有测试覆盖的生产功能也被排除,后续将逐步纳入统计口径。
21
+
22
+ **项目进展**:v2.50.0(2026-10-27 已发版),v2.47.0(2026-10-03,数据血缘 M1 表级 + M2 列级),v2.46.0(2026-10-01);E26→E32 里程碑(查询缓存/时间旅行、TTL、时间戳索引压缩、分片一致性哈希、HNSW-PQ 容量预测、热点预取、LRU)全部闭环。成熟度评级 **Beta+(工程验证成熟)**,未达通用生产级——依据 [maturity-evaluation-2026-09-04.md](docs/internal/audit/maturity-evaluation-2026-09-04.md) 五维实测(SQL 功能 5/5、测试工程化 5/5、安全对抗 4/5、性能 3/5、生态 2/5)。**单机嵌入场景(Node 应用内嵌、AI Agent 本地存储、小程序、实时看板)可生产探索**;核心交易链路不建议;TB 级 OLAP、亿级向量、万级 TPS 场景仍建议 PG/Oracle/DuckDB/LanceDB。开发参照基线与当前待办见 [docs/internal/audit/project-assessment-dev-reference-2026-10-03.md](docs/internal/audit/project-assessment-dev-reference-2026-10-03.md)。
23
+
24
+ **近期里程碑**(完整历史见 [CHANGELOG.md](CHANGELOG.md)):
25
+
26
+ - 🛡️ **安全体系**:安全模块默认 fail-closed(HTTP 仅绑定 127.0.0.1、JS UDF 默认禁用、认证/RBAC/列加密需显式开启)+ 17 项安全控制 + SOC2/ISO27001 合规路线图([SECURITY.md](SECURITY.md))
27
+ - 🦀 **Rust 可选加速层**:CRC32C / FNV-1a / Bloom / 向量化聚合与过滤的 napi-rs 实现,每个函数带 100% 等效纯 JS 回退,`npm install` 无需编译即可运行;核心引擎保持 100% 纯 JS。2026-10-27 评测发现的三处 AVX2 正确性 bug(min/max 全 NaN、utf8 批量编码截断、null bitmap ≥0x80 漏标)已于 2026-10-28 修复并重建 `native/index.node`,相关 Native 路径已恢复
28
+ - 🌐 **生态**:52 种语言/适配器 SDK + [CONTRIBUTING.md](CONTRIBUTING.md) 12 章节贡献指南 + [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) + Issue/PR 模板
29
+ - 🧪 **工程化**:826+ 个测试文件全量注册 run-all、c8 覆盖率门禁(lines 85%+)、Soak 稳定性测试、16 门禁发布审查(报告归档 [docs/internal/audit/](docs/internal/audit/))
30
+
31
+ > **业界惯例**:核心引擎用什么语言,就叫什么数据库。Pure-JS-DB 的核心引擎 100% 纯 JS,Rust 仅作为可选加速层(类似 Python 用 C 加速 numpy、Ruby 用 C 加速 OpenSSL)。`isNativeAvailable()` 为 false 时数据库功能完整可用,仅损失部分性能。
32
+
33
+ ---
34
+
35
+ ## 一分钟上手
36
+
37
+ ```javascript
38
+ import { Executor } from 'pure-js-db';
39
+
40
+ const db = new Executor();
41
+ db.executeSQL('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)');
42
+ db.executeSQL("INSERT INTO users VALUES (1, 'Alice', 28)");
43
+
44
+ const [result] = db.executeSQL("SELECT * FROM users WHERE age > ?", [20]);
45
+ console.log(result.rows);
46
+ // → [{ id: 1, name: 'Alice', age: 28 }]
47
+ ```
48
+
49
+ ---
50
+
51
+ ## 按场景快速入门
52
+
53
+ ### 场景 1:Web 服务需要并发写入
54
+
55
+ SQLite 式的单写排队?不需要。用 `BEGIN CONCURRENT` 让多个写操作并行执行,提交时自动冲突检测。
56
+
57
+ ```sql
58
+ -- 连接 A
59
+ BEGIN CONCURRENT;
60
+ INSERT INTO orders VALUES (101, 'widget', 29.99);
61
+ COMMIT;
62
+
63
+ -- 连接 B(与 A 同时执行)
64
+ BEGIN CONCURRENT;
65
+ INSERT INTO orders VALUES (102, 'gadget', 19.99);
66
+ COMMIT;
67
+ ```
68
+
69
+ 或者在 JS API 中使用 MVCC 事务:
70
+
71
+ ```javascript
72
+ const tx1 = await db.beginTransaction('mvcc');
73
+ const tx2 = await db.beginTransaction('mvcc');
74
+
75
+ await Promise.all([
76
+ tx1.execute("INSERT INTO orders VALUES (101, 'widget')"),
77
+ tx2.execute("INSERT INTO orders VALUES (102, 'gadget')")
78
+ ]);
79
+
80
+ await tx1.commit();
81
+ await tx2.commit(); // 冲突时自动重试(默认 3 次)
82
+ ```
83
+
84
+ 参见 [src/concurrency/mvcc.js](src/concurrency/mvcc.js) — `STABLE`
85
+
86
+ ### 场景 2:RAG 应用需要向量搜索
87
+
88
+ 关系数据和向量 embedding 存在同一个文件里。不需要 Milvus。
89
+
90
+ ```javascript
91
+ // 创建向量索引
92
+ db.executeSQL('CREATE VECTOR INDEX idx_embedding ON docs(embedding) TYPE hnsw');
93
+
94
+ // SQL 原生向量搜索
95
+ const [result] = db.executeSQL(
96
+ `SELECT content, L2_DISTANCE(embedding, ?) AS dist
97
+ FROM docs ORDER BY dist LIMIT 5`,
98
+ ['[0.2, 0.5, 0.1, 0.8]']
99
+ );
100
+ ```
101
+
102
+ 支持 HNSW、IVF/ADC、DiskANN、GPU/SIMD 加速,参见 [src/index/vector-index.js](src/index/vector-index.js) — `STABLE`
103
+
104
+ ### 场景 3:事件驱动架构需要 CDC
105
+
106
+ 不需要写触发器。`SELECT * FROM cdc_events` 直接查变更。
107
+
108
+ ```sql
109
+ -- 开启变更捕获(默认开启)
110
+
111
+ -- 查询最近 100 条变更
112
+ SELECT * FROM cdc_events ORDER BY timestamp DESC LIMIT 100;
113
+
114
+ -- 只查某张表的 INSERT
115
+ SELECT * FROM cdc_events WHERE table_name = 'orders' AND op = 'C';
116
+ ```
117
+
118
+ 高级场景使用消费者组 API(支持断线续传和至少一次语义),参见 [src/cdc/cdc-engine.js](src/cdc/cdc-engine.js) — `STABLE`
119
+
120
+ ### 场景 4:用自然语言操作数据库
121
+
122
+ 内置 MCP Server,AI 工具(Cursor / Claude Code / Claude Desktop)一键直连。
123
+
124
+ **方式 A:CLI 一键启动(推荐)**
125
+
126
+ ```bash
127
+ node scripts/mcp-server.mjs --seed # stdio 模式(供 Claude Desktop / Cursor 直连)
128
+ node scripts/mcp-server.mjs --transport http --port 3100 # HTTP/SSE 远程部署
129
+ node scripts/mcp-server.mjs --db-path ./data --allow-write # 持久化 + 写权限
130
+ ```
131
+
132
+ Claude Desktop 配置(`claude_desktop_config.json`):
133
+
134
+ ```json
135
+ {
136
+ "mcpServers": {
137
+ "pure-js-db": {
138
+ "command": "node",
139
+ "args": ["scripts/mcp-server.mjs", "--seed", "--allow-write"]
140
+ }
141
+ }
142
+ }
143
+ ```
144
+
145
+ **方式 B:编程方式**
146
+
147
+ ```javascript
148
+ import { createMcpServer, StdioTransport } from 'pure-js-db/src/mcp/index.js';
149
+
150
+ const mcp = await createMcpServer({
151
+ executor: db,
152
+ transport: 'stdio'
153
+ });
154
+ // AI 现在可以:查 schema、写 SQL、向量搜索、explain 查询计划
155
+ ```
156
+
157
+ 端到端落地演示(真实 stdio + HTTP 双模式,17 断言):`node demos/mcp-live-demo.mjs`(`npm run mcp:demo`)
158
+
159
+ 参见 [src/mcp/index.js](src/mcp/index.js) — `STABLE`
160
+
161
+ ### 场景 5:持久化到浏览器 / 小程序
162
+
163
+ ```javascript
164
+ import { PersistedDatabase, WeChatKVAdapter } from 'pure-js-db';
165
+
166
+ const db = new PersistedDatabase('myapp', new WeChatKVAdapter('myapp_db'));
167
+ await db.load();
168
+ // ... 正常使用 SQL ...
169
+ await db.save();
170
+ ```
171
+
172
+ 参见 [src/storage/persisted-db.js](src/storage/persisted-db.js) — `STABLE`
173
+
174
+ ### 场景 6:用 ActiveRecord 风格 ORM 操作数据库(v1.29.0+)
175
+
176
+ > ✅ **v2.50.0 已接线**:ORM 模块已从主入口导出 `defineModel` / `Schema` / `QueryBuilder` / `transaction` 等 API(F5 接线 2026-08-17),以下示例可直接运行。npm 子路径导入请使用 `pure-js-db/src/orm/index.js`。
177
+
178
+ 不写 SQL,直接用 Model/Schema/QueryBuilder/关联关系/钩子/事务。
179
+
180
+ ```javascript
181
+ import { Executor } from 'pure-js-db';
182
+ import { defineModel, Schema, transaction } from 'pure-js-db/orm';
183
+
184
+ const exec = new Executor();
185
+
186
+ const User = defineModel('User', new Schema({
187
+ id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
188
+ name: { type: 'TEXT', notNull: true, validate: { minLength: 1, maxLength: 50 } },
189
+ email: { type: 'TEXT', unique: true, validate: { email: true } },
190
+ age: { type: 'INTEGER', validate: { min: 0, max: 150 } },
191
+ }), {
192
+ tableName: 'users',
193
+ executor: exec,
194
+ relations: {
195
+ posts: { type: 'hasMany', model: 'Post', foreignKey: 'userId' },
196
+ profile: { type: 'hasOne', model: 'Profile', foreignKey: 'userId' },
197
+ },
198
+ hooks: {
199
+ beforeCreate: [(inst) => console.log('creating', inst.get('name'))],
200
+ },
201
+ });
202
+
203
+ await User.sync(); // CREATE TABLE IF NOT EXISTS users (...)
204
+
205
+ // CRUD
206
+ const alice = await User.create({ name: 'Alice', email: 'a@b.com', age: 30 });
207
+ const found = await User.findById(alice.get('id'));
208
+ found.set('age', 31);
209
+ await found.save();
210
+
211
+ // QueryBuilder 链式查询 + 关联预加载
212
+ const adults = await User.query()
213
+ .where('age', '>=', 18)
214
+ .orderBy('name', 'ASC')
215
+ .limit(10)
216
+ .with('posts')
217
+ .fetch();
218
+
219
+ // 事务(带自动回滚)
220
+ await transaction(exec, async () => {
221
+ const u1 = await User.create({ name: 'Bob' });
222
+ const u2 = await User.create({ name: 'Carol' });
223
+ // 任一抛错则全部回滚
224
+ });
225
+ ```
226
+
227
+ **ORM 10 文件架构**([src/orm/](src/orm/)):
228
+ - `schema.js` — Schema 列定义 + 8 类校验(min/max/length/enum/email/pattern/custom/required)
229
+ - `model.js` — `defineModel` 工厂 + ActiveRecord API(save/destroy/reload/loadRelation)
230
+ - `query-builder.js` — 链式 QueryBuilder(where/whereIn/whereNull/whereBetween/orderBy/limit/groupBy/having/with)
231
+ - `relations.js` — 4 种关联(hasOne/belongsTo/hasMany/manyToMany)+ eager/lazy load
232
+ - `hooks.js` — 11 个生命周期钩子 + HookAbortedError 中断机制
233
+ - `collection.js` — ModelCollection(数组兼容 + 分页元信息 + 批量 loadRelations)
234
+ - `errors.js` — 7 个错误类(Schema/Validation/NotFound/Relation/Transaction/HookAborted/ModelNotRegistered)
235
+ - `seeder.js` — Seeder 数据填充引擎(v1.31.0+,依赖排序 + 批次回滚 + 幂等执行 + 文件目录自动加载)
236
+ - `mixins/soft-delete.js` — 软删除 Mixin(v1.31.0+,`withSoftDelete()` 高阶函数 + withTrashed/onlyTrashed/restore/forceDestroy)
237
+ - `index.js` — 统一导出 + 全局模型注册表
238
+
239
+ ### 场景 7:完整业务系统案例
240
+
241
+ 参见 [examples/](examples/) 目录三个生产级案例:
242
+
243
+ | 案例 | 文件 | 覆盖特性 |
244
+ |---|---|---|
245
+ | **电商订单系统** | [examples/ecommerce-orders.mjs](examples/ecommerce-orders.mjs) | 6 张表 + 外键约束 + 事务保证订单/库存原子性 + 钩子自动生成订单号 + 关联查询 + 库存不足回滚 + 退款流程 |
246
+ | **博客/CMS 系统** | [examples/blog-cms.mjs](examples/blog-cms.mjs) | 5 张主表 + 2 张中间表 + 多对多关联(分类/标签)+ 评论树形自关联 + 软删除 + LIKE 搜索 + slug/excerpt 自动生成 + 事务回滚 |
247
+ | **IoT 时序数据** | [examples/iot-timeseries.mjs](examples/iot-timeseries.mjs) | 4 张表 + 高频批量写入(576 条/24h)+ 时间窗口聚合(按小时 GROUP BY)+ 时间范围查询 + 阈值告警 + 设备状态变更历史 + 数据保留策略 |
248
+
249
+ 运行:
250
+ ```bash
251
+ node examples/ecommerce-orders.mjs # 电商订单(9 业务场景)
252
+ node examples/blog-cms.mjs # 博客/CMS(12 业务场景)
253
+ node examples/iot-timeseries.mjs # IoT 时序(13 业务场景)
254
+ ```
255
+
256
+ ### 场景 8:生产案例压测(v1.31.1+)
257
+
258
+ [bench/](bench/) 目录下提供 3 个生产案例压测脚本,输出 TPS / p50 / p90 / p99 / max 延迟:
259
+
260
+ | 压测 | 文件 | 业务模型 | 压测场景 |
261
+ |---|---|---|---|
262
+ | **金融交易与反欺诈** | [bench/production-bench-finance.js](bench/production-bench-finance.js) | 6 表(accounts/transactions/risk_rules/fraud_alerts/balance_snapshots/audit_log) | B1 高频转账 TPS / B2 风控规则匹配 / B3 SERIALIZABLE 事务 / B4 对账聚合 / B5 审计日志哈希链 |
263
+ | **社交网络与推荐** | [bench/production-bench-social.js](bench/production-bench-social.js) | 6 表(users/friendships/posts/interactions/embeddings/recommendations) | S1 多跳好友查询 / S2 时间线分页 / S3 写读混合 / S4 向量召回+SQL 关联 / S5 热门话题聚合 |
264
+ | **日志分析与告警** | [bench/production-bench-logging.js](bench/production-bench-logging.js) | 5 表(sources/entries/patterns/alerts/aggregations) | L1 高频批量写入 / L2 LIKE 全文搜索 / L3 时间窗口聚合 / L4 物化视图刷新 / L5 实时告警流水线 |
265
+
266
+ 运行:
267
+ ```bash
268
+ npm run bench:finance # 单独跑金融
269
+ npm run bench:social # 单独跑社交
270
+ npm run bench:logging # 单独跑日志
271
+ npm run bench:production # 一次跑全部 3 个(15 个场景)
272
+ ```
273
+
274
+ 参考输出格式(每场景一行):
275
+ ```
276
+ ═══ B1. 高频转账 TPS(OLTP) ═══
277
+ ops=2000 tps=661.6 avg=1.509ms p50=1.245ms p90=2.643ms p99=3.395ms max=5.985ms
278
+ ```
279
+
280
+ ---
281
+
282
+ ## 生产就绪度矩阵
283
+
284
+ | 模块 | 状态 | 说明 |
285
+ |---|:---:|---|
286
+ | SQL 解析器 (tokenizer + parser + AST) | **STABLE** | Phase 0 完成,覆盖 DDL/DML/DQL/TCL + PL/pgSQL 子集 + MERGE + JSON_TABLE + CURSOR + TRIGGER |
287
+ | 内存执行引擎 (executor) | **STABLE** | Phase 1 完成,CRUD、JOIN、聚合、参数绑定、窗口函数 11 种、递归 CTE、RETURNING |
288
+ | 持久化 (KV 适配器 + 序列化) | **STABLE** | Phase 1 完成,8 种编码器、脏表增量保存、7 种 KV 适配器 |
289
+ | B+ 树索引 + 11 种索引 | **STABLE** | B+Tree / Off-Heap B+Tree / Hash / Adaptive Hash / Bitmap / BRIN / GiST / GIN / R-Tree / Full-text + 11 种向量索引 |
290
+ | 查询优化器 | **STABLE** | CBO + 谓词下推 + 子查询去关联 + CSE + JIT 表达式编译 + Adaptive Optimizer + Plan Cache |
291
+ | HTAP 混合存储 | **STABLE** | 行存 + 列存 + LSM-Tree + 冷热分层(⚠️ mmap / Off-Heap / SharedArrayBuffer 代码存在但未接线) |
292
+ | 向量搜索 (HNSW/IVF/DiskANN/PQ/SQ) | **STABLE** | 11 种向量索引 + SIMD (WASM) + GPU (WebGPU/WebGL) + Rust 原生 (AVX-512) + 联邦搜索 + 分布式搜索 + 自动调优 |
293
+ | CDC 变更捕获 | **STABLE** | 3 阶段全实现:WAL hook、消费者组、offset 持久化 + Debezium 兼容 + DDL 捕获 + Schema History |
294
+ | MVCC 并发写入 | **STABLE** | READ COMMITTED + REPEATABLE READ + MVCC + OCC + 悲观锁 + 2PC + 3PC + GlobalTxCoordinator + SSI/Lock-Free 已接入生产路径(F3/F4 接线:2026-08-17),`BEGIN ISOLATION LEVEL SERIALIZABLE` 语法触发,无需额外配置 |
295
+ | MCP Server | **STABLE** | 26 个 LLM 工具(schema/query/vector-search/explain/transaction/index/backup/cdc/monitor),stdio + HTTP/SSE 双传输,`node scripts/mcp-server.mjs` 一键启动 |
296
+ | 全文搜索 (倒排 + BM25) | **STABLE** | 中英文分词 + BM25 评分 + GIN 索引 |
297
+ | 审计日志 | **STABLE** | 防篡改哈希链 + RSA 数字签名 + SQL 脱敏 + 文件轮转 + 完整性验证 |
298
+ | 物化视图 | **STABLE** | AST 语义路由 + 增量刷新 |
299
+ | Regular VIEW / Partial Index / PL/pgSQL | **STABLE** | v1.24.0 A1/A2/A3 补全 |
300
+ | TLS / HTTPS 传输 | **STABLE** | v1.24.0 B1 支持 cert/key、PFX、mTLS |
301
+ | SQL 注入检测 | **STABLE(需显式启用)** | v1.24.0 B2 10 类注入特征识别(`src/security/sql-injection-detector.js`),已接入用户 SQL 直通端点 `/api/query` `/api/explain` `/api/v1/query*`(2026-08-14 安全审计加固)。⚠️ **默认关闭**,生产部署须调用 `executor.setSQLInjectionDetector(new SQLInjectionDetector())` 显式启用,否则不对 SQL 做注入检测。
302
+ | 监控告警(AlertManager + Prometheus) | **STABLE** | v1.24.0 C1 阈值规则 + Webhook 通道 + 抑制 |
303
+ | 自动故障转移 (Raft Failover) | **STABLE** | v1.24.0 C2 Leader 宕机→重选举 + 告警联动 |
304
+ | TPC-H 基准 | **STABLE** | v1.24.0 D1 标准 8 表 + Q1/Q3/Q4/Q5/Q6 |
305
+ | **REST + GraphQL + OpenAPI + WebSocket + SSE 五位一体 API** | **STABLE** | v1.25.0 P2-7/P2-8 完成;零依赖 GraphQL Server + Swagger UI + RFC 6455 WebSocket |
306
+ | **Sequelize / TypeORM / Prisma ORM 适配器** | **STABLE** | ORM 13 文件 + 3 适配器已接入生产路径(F5 接线:2026-08-17),`src/index.js` 导出 `defineModel`/`Schema`/`QueryBuilder` 等全部标识符,DoD 6/6 全满足 |
307
+ | **CLI 工具链(migrate / dump / restore)** | **STABLE** | v1.25.0 P2-9/P2-10 完成 |
308
+ | **Live Query 增量推送** | **STABLE** | 实时查询增量推送 + 时间旅行(SELECT AS OF)已接入生产路径(F6 接线:2026-08-17),`HistoricalSnapshotReader`/`makeReadonly` 已导出,DoD 6/6 全满足 |
309
+ | LSM-Tree 存储引擎 | **STABLE** | MemTable + SSTable + Compaction + WAL + BloomFilter + BlockCache + DatabaseManager/FullTextSearch/SSTableRepair 已接入生产路径(F10 接线:2026-08-17) |
310
+ | 分布式分片 + scatter-gather 下推 | **STABLE** | 一致性哈希 + filter/projection/agg/LIMIT 下推 + 二次聚合 + K 路归并 |
311
+ | 多语言 SDK(40+ 语言目录) | **STABLE** | 仓库 `sdk/` + `src/sdk/` 下 40+ 语言目录(React Native Hermes JSI 嵌入式通过 `pure-js-db/sdk` 子入口可达) |
312
+ | Raft 共识 | **STABLE** | v1.30.0+ 持久化状态恢复(currentTerm/votedFor)+ 主动快照 + InstallSnapshot RPC + RaftLog 索引修正;满足 Raft Figure 2 持久化要求与 Figure 12 快照安装语义 |
313
+ | 只读副本 (Read Replica) | **STABLE** | ReadReplica + ReadWriteRouter + 主从/多主复制已接入生产路径(F2 接线:2026-08-17),`ReplicationMaster`/`Replica`/`MultiMasterReplication` 已导出,DoD 6/6 全满足 |
314
+ | iOS / Android 原生 SDK | **STABLE** | v1.30.2+ iOS(Swift 5.7+ async/await + URLSession,SPM 包 iOS 13+/macOS 10.15+,零外部依赖)+ Android(Kotlin + kotlinx-coroutines,suspend 函数 + HttpURLConnection,JVM 11+,零 JSON 库依赖)+ 三端 API 等价性(query/select/execute/batch/prepare/transaction/withTransaction/sync 等 14+ 核心方法)+ 完整错误类型体系(Connection/Timeout/Query/Transaction)+ 14 项静态验证测试 |
315
+ | **生产案例压测(金融/社交/日志)** | **STABLE** | v1.31.1+ 3 个生产案例 15 个场景压测(B1-B5 / S1-S5 / L1-L5);输出 TPS / p50 / p90 / p99 / max;npm run bench:production 一键运行 |
316
+ | **测试覆盖率(c8)** | **STABLE** | v1.31.2+ c8 覆盖率报告(lines/branches/functions/statements 阈值 85/75/80/85)+ 25+ 个原未注册测试文件接入 run-all.js + SSI/RowLock/LSM扩展/Worker池/Disruptor 等模块已通过 E23 阶段 3 入口拆分接入生产路径 |
317
+ | **c8 全局覆盖率达标(85%)** | **STABLE** | v1.32.0+ c8 全局 lines 覆盖率从 64.14% 提升到 85% 阈值达标;新增 15 个测试文件 477 用例覆盖 BloomFilter/AsyncMutex/UDT/TenantManager/LSM Compactor/Disruptor/SharedCache/IOThreadPool/Monitor/CDC Handlers/ORM Schema/LiveQueryManager/ORM QueryBuilder/LockFreeManager 等模块 |
318
+ | **Soak 长期稳定性测试** | **STABLE** | v1.32.0+ 30 秒持续负载 4 场景 15 断言:①INSERT/SELECT 混合(~137K ops)②UPDATE/DELETE 周期(~2263 cycles)③索引一致性(1837 iterations)④事务回滚(7322 tx);验证吞吐/错误率/延迟/数据一致性 |
319
+ | **SOC2/ISO27001 合规准备** | **STABLE** | v1.32.0+ [SECURITY.md](SECURITY.md) 11 章节完整合规文档:17 项已实现安全控制 + 13 项 SOC2 信任服务类别 + 37 项 ISO27001 Annex A 控制 + 7/8 阶段认证路线图 + VDP 漏洞披露 + 严重性分级 + 事件响应流程 |
320
+ | **52 种 SDK + 社区贡献基础设施** | **STABLE** | v1.32.0+ SDK 从 10 扩展到 52(30 新语言:C#/Ruby/Dart/Kotlin/Scala/Lua/Elixir/R/Julia/C/C++/ObjC/Perl/Haskell/Clojure/F#/Groovy/Nim/Crystal/Zig/OCaml/D/Erlang/Swift Server/VB/Pascal/Phoenix/Django/SQLAlchemy/EF + 12 ORM/驱动/IDE:Prisma/Sequelize/TypeORM/ActiveRecord/Hibernate/JDBC/PDO/ADO.NET/DB-API/DBeaver/DataGrip/TablePlus)+ [CONTRIBUTING.md](CONTRIBUTING.md) 12 章节贡献指南 + [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) + Issue/PR 模板 |
321
+
322
+ > **使用建议**:`STABLE` 模块可用于生产环境;`EXPERIMENTAL` 模块建议先在测试环境验证;`UNSTABLE` 模块仅供学习或原型验证。
323
+
324
+ ---
325
+
326
+ ## 安装
327
+
328
+ ```bash
329
+ npm install pure-js-db
330
+ ```
331
+
332
+ 要求 Node.js >= 18.0.0(ESM 模块)。
333
+
334
+ ---
335
+
336
+ ## 特性一览
337
+
338
+ | 能力 | 说明 |
339
+ |---||
340
+ | SQL 解析 | 手写状态机 + 递归下降解析器;DDL/DML/DQL/TCL/PL/pgSQL 子集;MERGE / JSON_TABLE / CURSOR / TRIGGER / RETURNING |
341
+ | 执行引擎 | CRUD、子查询、JOIN、聚合、集合操作、11 种窗口函数、递归 CTE |
342
+ | 索引(11 种) | B+Tree / Off-Heap B+Tree / Hash / Adaptive Hash / Bitmap / BRIN / GiST / GIN / R-Tree / Full-text + Partial Index |
343
+ | 视图 | Regular VIEW + Materialized VIEW(含增量刷新) |
344
+ | 存储过程 | PL/pgSQL 解释器(IF/LOOP/WHILE/FOR/EXCEPTION/RETURN) |
345
+ | 向量搜索(11 种) | HNSW / HNSW-PQ / IVFPQSQ / DiskANN / PQ / SQ / Semantic + SIMD (WASM) + GPU (WebGPU/WebGL) + Rust 原生 (AVX-512) + 联邦搜索 + 分布式搜索 |
346
+ | 全文搜索 | 倒排索引 + BM25 + 中英文分词 |
347
+ | 并发控制 | MVCC + OCC + 悲观锁 + READ COMMITTED + REPEATABLE READ + **SERIALIZABLE**(M4 已接线,`BEGIN ISOLATION LEVEL SERIALIZABLE` 触发) + 2PC + 3PC + GlobalTxCoordinator(SSI 已接线;⚠️ Lock-Free 未接线) |
348
+ | 存储 | HTAP 行+列混合 + LSM-Tree + 冷热分层 + mmap + Off-Heap + SharedArrayBuffer + 7 种 KV 适配器 |
349
+ | 分布式 | 一致性哈希分片 + scatter-gather 下推 + 2PC/3PC + 自动故障转移 + Read Replica(主从/多主复制已接线,见矩阵) |
350
+ | 安全 | RBAC + SQL 防火墙 + SQL 速率限制 + TLS/HTTPS + 速率限制 + 审计哈希链 + RSA 数字签名 + 列加密 + 字段加密 + 行级安全(RLS) + SQL注入检测 + API Key + JWT + 数据脱敏 + 安全擦除(⚠️ **认证/RBAC/列加密/RLS/注入检测默认关闭,生产部署必须显式配置**,见 [SECURITY.md](SECURITY.md) §2.2) |
351
+ | 可观测 | CDC + Debezium 兼容 + DDL 捕获 + Live Query + 审计日志 + Prometheus exporter + Grafana + AlertManager + OpenTelemetry + EXPLAIN ANALYZE(⚠️ SELECT AS OF 时间旅行 未接线) |
352
+ | AI 接入 | MCP Server(26 个 LLM 工具)+ Text-to-SQL + CHAT/EMBED SQL 函数 + 多 Provider(OpenAI/智谱/百度/通义/Ollama) |
353
+ | **HTTP API(五位一体)** | REST + GraphQL(零依赖)+ OpenAPI 3.0 + Swagger UI + WebSocket(RFC 6455)+ SSE |
354
+ | **ORM 适配器** | ✅ 已导出 `defineModel`/`Schema`/`QueryBuilder`(F5 接线 2026-08-17,见矩阵) |
355
+ | **CLI 工具链** | migrate(迁移)+ dump(导出)+ restore(恢复)+ REPL 交互式 shell |
356
+ | **多语言 SDK(52 种)** | 10 核心语言(JS/Python/PHP/Go/Java/Rust/React Native/微信小程序/iOS Swift/Android Kotlin)+ 30 新语言(C#/Ruby/Dart/Kotlin/Scala/Lua/Elixir/R/Julia/C/C++/ObjC/Perl/Haskell/Clojure/F#/Groovy/Nim/Crystal/Zig/OCaml/D/Erlang/Swift Server/VB/Pascal/Phoenix/Django/SQLAlchemy/EF)+ 12 ORM/驱动/IDE 插件(Prisma/Sequelize/TypeORM/ActiveRecord/Hibernate/JDBC/PDO/ADO.NET/DB-API/DBeaver/DataGrip/TablePlus)。注:"52 种"为含插件的营销口径;仓库 `sdk/` + `src/sdk/` 实际为 40+ 语言目录。**版本同步口径(G-5,2026-10-28)**:`sync-versions` 单一来源同步仅覆盖 `src/sdk/` 下 4 个核心 SDK(Java/Python/PHP/Rust)+ `package.json`;`sdk/` 下 32 个语言 SDK 与 12 个适配器版本号独立(`0.1.0-alpha`,Status: ALPHA,无测试),不随核心版本自动同步 |
357
+ | **监控告警** | Prometheus + Grafana Dashboard + AlertManager(Webhook 通道) |
358
+
359
+ ---
360
+
361
+ ## 模块详解
362
+
363
+ ### SQL 解析(~2,159 行)
364
+
365
+ | 文件 | 说明 |
366
+ |:-----|:------|
367
+ | `src/parser/tokenizer.js` | 手写状态机词法分析器,支持 SQL 关键字、标识符、数字、字符串、注释 |
368
+ | `src/parser/parser.js` | 递归下降解析器,优先级爬升法解析表达式 |
369
+ | `src/parser/ast.js` | 30+ 种 AST 节点类,Visitor 模式,astToString 工具 |
370
+
371
+ 支持语句:`SELECT` / `INSERT` / `UPDATE` / `DELETE` / `CREATE TABLE` / `DROP TABLE` / `CREATE INDEX` / `DROP INDEX` / `CREATE MATERIALIZED VIEW` / `DROP MATERIALIZED VIEW` / `BEGIN` / `BEGIN CONCURRENT` / `COMMIT` / `ROLLBACK`
372
+
373
+ 支持 JOIN 类型:`INNER JOIN` / `LEFT JOIN` / `RIGHT JOIN`
374
+
375
+ 支持集合操作:`UNION` / `UNION ALL` / `EXCEPT` / `INTERSECT`
376
+
377
+ ### 执行引擎 + 序列化 + 持久化(~2,649 行)
378
+
379
+ | 文件 | 说明 |
380
+ |:-----|:------|
381
+ | `src/executor/database.js` | Database / Table / ColumnDef,CRUD,约束检查,事务 undo log |
382
+ | `src/executor/executor.js` | SQL AST 执行引擎,JOIN / GROUP BY / ORDER BY / LIMIT / 聚合 / 集合操作 |
383
+ | `src/executor/expression.js` | 表达式求值器,参数绑定,LIKE 模式匹配 |
384
+ | `src/serializer/codecs.js` | 8 种类型编码器:INT8/16/32/48、FLOAT64、BOOL、TEXT_DICT/LONG |
385
+ | `src/serializer/serializer.js` | 列式序列化/反序列化,自动分页 |
386
+ | `src/storage/kv-adapter.js` | Memory / LocalStorage / WeChat(miniprogram) 三种 KV 适配器 |
387
+ | `src/storage/persisted-db.js` | 继承 Database,脏表标记增量保存,索引持久化 |
388
+
389
+ ### 向量搜索(~2,500+ 行)
390
+
391
+ | 文件 | 说明 |
392
+ |:-----|:------|
393
+ | `src/index/vector-index.js` | IVF + ADC,ANN 搜索,L2/Cosine/IP 距离 |
394
+ | `src/index/hnsw-index.js` | HNSW 高精度 ANN |
395
+ | `src/index/diskann-index.js` | 十亿级磁盘向量索引 |
396
+ | `src/index/ivfpqsq-index.js` | IVF-PQ + SQ 标量量化混合 |
397
+ | `src/vector/simd-distance.js` | SIMD 距离计算 |
398
+ | `src/vector/gpu-distance.js` | GPU 加速(WebGPU / WebGL / CPU 回退) |
399
+ | `src/index/index-auto-tuner.js` | 自动索引调优 |
400
+
401
+ ### 并发与事务(~1,200+ 行)
402
+
403
+ | 文件 | 说明 |
404
+ |:-----|:------|
405
+ | `src/concurrency/mvcc.js` | MVCC 管理器,快照隔离,写偏斜检测 |
406
+ | `src/concurrency/lock-manager.js` | 共享锁 / 排他锁 / 意向锁,死锁检测 |
407
+ | `src/concurrency/lockfree-executor.js` | ⚠️ 无锁执行路径代码存在但未接线(生产不可达) |
408
+ | `src/concurrency/async-mutex.js` | 异步互斥锁(Promise 队列序列化) |
409
+ | `src/transaction/` | READ UNCOMMITTED / READ COMMITTED / REPEATABLE READ + **SERIALIZABLE**(M4 已接线)(⚠️ SSI 代码存在但未接线) |
410
+
411
+ ### CDC 变更捕获(~400+ 行)
412
+
413
+ | 文件 | 说明 |
414
+ |:-----|:------|
415
+ | `src/cdc/cdc-engine.js` | 3 阶段全实现:WAL hook、消费者组、offset 持久化、列投影、行过滤 |
416
+ | `src/sync/change-log.js` | 离线变更日志,浏览器端使用 |
417
+
418
+ ### MCP Server(~600+ 行)
419
+
420
+ | 文件 | 说明 |
421
+ |:-----|:------|
422
+ | `src/mcp/mcp-server.js` | MCP 服务器核心 |
423
+ | `src/mcp/tools/execute-sql.js` | 执行 SQL 工具 |
424
+ | `src/mcp/tools/vector-search.js` | 向量搜索工具 |
425
+ | `src/mcp/tools/text-to-sql.js` | 自然语言转 SQL 工具 |
426
+ | `src/mcp/transport/stdio.js` | stdio 传输 |
427
+ | `src/mcp/transport/http.js` | HTTP 传输 |
428
+
429
+ ### B+ 树索引(~788 行)
430
+
431
+ | 文件 | 说明 |
432
+ |:-----|:------|
433
+ | `src/index/btree.js` | B+ 树核心(order=4),插入自动分裂,删除自动合并 |
434
+ | `src/index/btree-index.js` | BTreeIndex 封装,唯一约束检查,批量构建 |
435
+
436
+ ### 查询优化器(~763 行)
437
+
438
+ | 文件 | 说明 |
439
+ |:-----|:------|
440
+ | `src/optimizer/optimizer.js` | 基于成本的索引选择、统计信息、复合索引前缀匹配 |
441
+
442
+ ### 全文搜索(~400+ 行)
443
+
444
+ | 文件 | 说明 |
445
+ |:-----|:------|
446
+ | `src/index/fulltext/inverted-index.js` | 倒排索引,BM25 排序,动态增删 |
447
+ | `src/index/fulltext/tokenizer.js` | 中英文分词器 |
448
+
449
+ ### 其他模块
450
+
451
+ | 模块 | 说明 |
452
+ |:-----|:------|
453
+ | `src/audit/` | 审计日志、防篡改哈希链、数字签名 |
454
+ | `src/view/` | 物化视图、AST 语义路由 |
455
+ | `src/sharding/` | 一致性哈希分片、2PC/3PC、查询下推 |
456
+ | `src/cluster/` | Raft 共识 + 持久化状态 + 快照 + 故障转移 |
457
+ | `src/replication/` | Read Replica(⚠️ 主从/多主复制代码存在但未接线) |
458
+ | `src/security/` | RBAC、SQL 防火墙、SQL 速率限制、列加密、字段加密、行级安全(RLS)、SQL注入检测、API Key、认证(Auth)、JWT、数据脱敏、安全擦除 |
459
+ | `src/http-server/` | RESTful API 服务 |
460
+
461
+ ---
462
+
463
+ ## 文档导航
464
+
465
+ 完整文档清单见 [docs/DOC-INDEX.md](docs/DOC-INDEX.md)。以下为快速入口:
466
+
467
+ ### 按角色快速选择
468
+
469
+ | 角色 | 推荐文档 |
470
+ |------|---------|
471
+ | 🚀 第一次使用 | [QUICK-START.md](docs/QUICK-START.md) — 5 分钟上手 |
472
+ | 💻 应用开发者 | [USER-GUIDE.md](docs/USER-GUIDE.md) — 完整使用手册(20 章节,覆盖 SQL/ORM/向量/全文/CDC/复制/分布式/安全/监控/AI) |
473
+ | 🔌 多语言接入 | [SDK-GUIDE.md](docs/SDK-GUIDE.md) — 52 种 SDK + 12 种 ORM 适配器 + JDBC/PDO/ADO.NET/DB-API 驱动 |
474
+ | 🛠️ 运维 / DBA | [DEPLOYMENT-GUIDE.md](docs/DEPLOYMENT-GUIDE.md) — 单机/Docker/K8s 部署 + 监控告警 + 备份恢复 |
475
+ | 🖥️ 用 Web UI | [Web UI 工具](#web-ui-工具) — Studio IDE(开发调试)+ Admin Panel(运维管理) |
476
+ | 🏗️ 架构师 / 决策者 | [COMPARISON 目录](docs/comparison/) — 项目成熟度深度评估 + 主流数据库对比 |
477
+ | 📖 查 API 细节 | [API-REFERENCE.md](docs/API-REFERENCE.md) — 66 章节 API 参考手册 |
478
+ | 🤖 AI 集成 | [AI-FEATURES-GUIDE.md](docs/AI-FEATURES-GUIDE.md) — MCP Server / AI_FUNCTION / Text-to-SQL |
479
+ | 🔧 架构理解 | [ARCHITECTURE.md](ARCHITECTURE.md) |
480
+ | 🔒 安全 / 合规 | [SECURITY.md](SECURITY.md) — SOC2/ISO27001 合规路线图 + 17 项安全控制 + VDP 漏洞披露 + [USER-GUIDE §14 安全](docs/USER-GUIDE.md#14-安全rbac--加密--sql-防火墙) + [CVE-RESPONSE-PROCESS.md](docs/CVE-RESPONSE-PROCESS.md) |
481
+ | 🤝 社区贡献 | [CONTRIBUTING.md](CONTRIBUTING.md) — 12 章节贡献指南 + [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — Contributor Covenant 2.1 |
482
+
483
+ ### Web UI 工具
484
+
485
+ Pure-JS-DB 内置两套 Web UI,零外部依赖:
486
+
487
+ - **Studio IDE** — 开发调试工具(Schema 设计 + SQL 编辑器 + ER 图 + 数据浏览)
488
+ ```bash
489
+ node src/studio/server.js --schema ./examples/schema.pjdb --port 3000
490
+ ```
491
+ - **Admin Panel** — 运维管理工具(SQL 查询 + 监控面板 + 备份管理)
492
+ ```bash
493
+ # 终端 1:先启动 HTTP API(可加 --db-path 持久化)
494
+ node src/cli.js --server 3000 --db-path ./data
495
+
496
+ # 终端 2:再启动 Admin Panel(同端口代理 /api)
497
+ node admin-ui/server.js --port 8080 --api-url http://127.0.0.1:3000
498
+ # 浏览器打开 http://127.0.0.1:8080
499
+ ```
500
+
501
+ 以上两套 Web UI 均无需额外依赖,直接按上文命令启动即可。
502
+
503
+ ---
504
+
505
+ ## API 参考
506
+
507
+ 所有 API 均可通过 `import { ... } from 'pure-js-db'` 导入。完整 API 列表见 [API-REFERENCE.md](docs/API-REFERENCE.md)(66 章节,116KB)。
508
+
509
+ ### 核心类
510
+
511
+ | 类 | 说明 |
512
+ |:---|:------|
513
+ | `Executor` | 主要入口,`executeSQL(sql, params?)` 执行任意 SQL |
514
+ | `Database` | 底层数据库状态管理 |
515
+ | `PersistedDatabase` | 可持久化的 Database,`load()` / `save()` |
516
+ | `QueryOptimizer` | 基于成本的查询优化器 |
517
+ | `MVCCManager` | MVCC 并发事务管理器 |
518
+ | `CDCEngine` | CDC 变更捕获引擎 |
519
+ | `McpServer` | MCP 服务器(AI 直连) |
520
+ | `LockManager` | 锁管理器(共享锁 / 排他锁 / 意向锁) |
521
+ | `ShardManager` | 分布式分片管理器 |
522
+ | `GlobalTransactionCoordinator` | 全局分布式事务协调者(2PC) |
523
+
524
+ ### 事务控制
525
+
526
+ ```sql
527
+ -- 标准事务
528
+ BEGIN;
529
+ INSERT INTO users VALUES (1, 'Alice');
530
+ COMMIT;
531
+
532
+ -- 并发事务(MVCC,读写互不阻塞,提交时冲突检测)
533
+ BEGIN CONCURRENT;
534
+ INSERT INTO orders VALUES (101, 'widget', 29.99);
535
+ COMMIT;
536
+
537
+ -- 指定隔离级别
538
+ BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
539
+ SELECT * FROM users WHERE id = 1;
540
+ COMMIT;
541
+ ```
542
+
543
+ ### CDC 查询
544
+
545
+ ```sql
546
+ -- 查看所有变更
547
+ SELECT * FROM cdc_events ORDER BY timestamp DESC;
548
+
549
+ -- 按表过滤
550
+ SELECT * FROM cdc_events WHERE table_name = 'users';
551
+
552
+ -- 按操作类型过滤
553
+ SELECT * FROM cdc_events WHERE op IN ('C', 'U');
554
+ ```
555
+
556
+ > CDC 事件 `op` 字段:`C` = INSERT,`U` = UPDATE,`D` = DELETE,`S` = SNAPSHOT
557
+
558
+ ---
559
+
560
+ ## 性能定位与适用场景
561
+
562
+ ### 诚实面对性能差距
563
+
564
+ Pure-JS-DB 的核心引擎 **100% 纯 JavaScript**,与 SQLite (C) 和 DuckDB (C++) 存在 **数量级差距**:
565
+
566
+ | 场景 | Pure-JS-DB | SQLite | DuckDB | 差距 |
567
+ |------|-----------|--------|--------|------|
568
+ | DELETE 1K (有触发器) | 0.56ms | 0.02ms | 0.05ms | **28x / 11x** |
569
+ | JOIN 500行 | 2.37ms | 0.3ms | 0.1ms | **8x / 24x** |
570
+ | WINDOW FUNCTION 1K | 486ms | 8.4ms | 2ms | **58x / 243x** |
571
+
572
+ **差距根源**:
573
+ - V8 解释执行 vs C/C++ 编译执行
574
+ - JS 对象分散内存 vs 连续内存页式管理
575
+ - GC 自动回收开销 vs 手动内存管理
576
+ - 逐行解释执行 vs 字节码虚拟机/向量化执行
577
+
578
+ ### Rust NAPI 的真实覆盖范围
579
+
580
+ Rust NAPI 模块 **仅加速 ~1% 的计算原语**,不解决核心引擎性能问题:
581
+
582
+ ```
583
+ Pure-JS-DB 架构:
584
+ ┌─────────────────────────────────────────────────────────────┐
585
+ │ 核心引擎 (100% JS) │
586
+ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
587
+ │ │ Parser │ │Executor │ │ Storage │ │Transaction│ │
588
+ │ │ ~30K行 │ │ ~40K行 │ │ ~35K行 │ │ ~25K行 │ │
589
+ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
590
+ │ │
591
+ │ ┌─────────────────────────────────────────────────────┐ │
592
+ │ │ Rust NAPI 加速层 (~1% 覆盖) │ │
593
+ │ │ CRC32C │ FNV-1a │ Bloom │ L2距离 │ min/max │ sum │ │
594
+ │ │ 这些只是计算原语,不是核心引擎! │ │
595
+ │ └─────────────────────────────────────────────────────┘ │
596
+ └─────────────────────────────────────────────────────────────┘
597
+ ```
598
+
599
+ **关键问题**:
600
+ - 每次 SQL 执行仍需:JS 解析 → JS 执行 → JS 存储 → JS 事务管理
601
+ - NAPI 调用开销 (~300ns) 在频繁调用中抵消 SIMD 收益
602
+ - 核心引擎的解析/执行/存储/事务仍是 JS 瓶颈
603
+
604
+ ### Pure-JS-DB 的核心价值
605
+
606
+ **不是性能,而是部署灵活性和零依赖**:
607
+
608
+ | 场景 | 价值 | 性能要求 |
609
+ |------|------|---------|
610
+ | **小程序/浏览器嵌入式** | 唯一纯 JS 实现,零依赖运行 | 可接受 |
611
+ | **AI Agent 本地数据库** | MCP 原生集成,一个文件搞定 | 可接受 |
612
+ | **边缘函数/Serverless** | 冷启动快,无编译依赖 | 可接受 |
613
+ | **教学/原型开发** | 代码可读可改,学习数据库原理 | 不敏感 |
614
+ | **离线优先应用** | 本地存储 + 同步能力 | 可接受 |
615
+
616
+ **不适合的场景**:
617
+ - ❌ 高并发 OLTP(用 PostgreSQL)
618
+ - ❌ TB 级 OLAP(用 DuckDB)
619
+ - ❌ 亿级向量搜索(用 Milvus)
620
+ - ❌ 金融核心交易(用 Oracle)
621
+
622
+ ### JS 性能优化方向(2024-2025)
623
+
624
+ 基于最新技术研究,JS 性能优化路径:
625
+
626
+ | 技术 | 预期收益 | 状态 | 说明 |
627
+ |------|---------|------|------|
628
+ | **TypedArray 优化** | 3-10x | ✅ 已应用 | Float32Array/Int32Array 连续内存 |
629
+ | **V8 TurboFan 热点优化** | 2-5x | 🔶 声称,未独立复现 | 热点函数自动 JIT 编译(2026-10-27 评测未单独复现该加速比) |
630
+ | **WASM SIMD 自动检测** | 5-10x | 🔶 声称,未独立复现 | 现代 TypedArray 库支持(同上,评测未复现) |
631
+ | **内存池复用** | 减少 GC 70% | 🔶 部分 | 减少对象创建开销 |
632
+ | **WASM 核心引擎** | 2-5x | 📋 规划中 | 见 [WASM 可行性分析](docs/architecture/wasm-feasibility-analysis.md) |
633
+ | **AVX-512 扩展** | 2-3x | 📋 规划中 | Rust NAPI 扩展 |
634
+
635
+ **参考**:
636
+ - V8 四级编译管道:Ignition → Sparkplug → Maglev → TurboFan (Node.js 24/25)
637
+ - V8 13.6/14.1 新增 Float16Array、WebAssembly Memory64
638
+ - Modern TypedArray 库提供 WASM SIMD 自动加速 (5-10x)
639
+ - SimSIMD 提供零拷贝 NAPI 调用
640
+
641
+ ---
642
+
643
+ ## 性能基准
644
+
645
+ ### 双引擎架构
646
+
647
+ Pure-JS-DB 提供 **双引擎模式**,根据运行环境自动选择最优执行路径:
648
+
649
+ | 引擎 | 适用环境 | 性能特点 | 加速方式 |
650
+ |------|---------|---------|---------|
651
+ | **纯 JS 引擎** | 浏览器/小程序/边缘函数 | 零依赖,v2.27.0 优化后 DELETE 0.56ms/1K行 | 批量触发器合并 + WHERE 条件下推 |
652
+ | **Rust NAPI 加速** | Node.js + Rust 模块 | SIMD 加速,聚合计算旧基准宣称最高 **45x**(2026-10-27 独立性能评测发现加速层多数路径未在生产接线,实际收益有限;评测暴露的 AVX2 正确性 bug 已于 2026-10-28 修复;见 `docs/评估/Pure-JS-DB-独立第三方综合评测报告-2026-10-27.md`) | AVX2/AVX-512 指令集 |
653
+
654
+ ### 自动引擎选择
655
+
656
+ ```javascript
657
+ import { isNativeAvailable, getAccelerationBackend } from 'pure-js-db/native/native-acceleration.js';
658
+
659
+ // 自动检测
660
+ if (isNativeAvailable()) {
661
+ console.log('使用 Rust NAPI 加速引擎');
662
+ // 聚合计算、向量搜索等自动使用 SIMD 加速
663
+ } else {
664
+ console.log('使用纯 JS 引擎');
665
+ // 透明回退到纯 JS 实现,算法完全一致
666
+ }
667
+
668
+ // 后端标识: "native" | "rust-napi" | "js"
669
+ const backend = getAccelerationBackend();
670
+ ```
671
+
672
+ **选择逻辑**:
673
+ 1. Node.js 环境 + Rust 模块已编译 → 使用 **Rust NAPI 加速**
674
+ 2. 浏览器/小程序/边缘函数 → 使用 **纯 JS 引擎**
675
+ 3. Rust 模块加载失败 → 自动回退到 **纯 JS 引擎**
676
+
677
+ ### 纯 JS 引擎性能 (Node.js V8)
678
+
679
+ | 场景 | Pure-JS-DB (JS) | SQLite | DuckDB | 说明 |
680
+ |------|:--------------:|:------:|:------:|------|
681
+ | **DELETE 1K (有触发器)** | **0.56ms** | 0.02ms | 0.05ms | 相对 SQLite 28x |
682
+ | **JOIN 500行** | **2.37ms** | 0.3ms | 0.1ms | 相对 SQLite 8x |
683
+ | **JOIN 5K行** | **15.12ms** | 3ms | 1ms | 自适应策略选择 |
684
+ | **SELECT ALL 1K** | **5.16ms** | 0.62ms | 0.3ms | |
685
+ | **AGGREGATE 1K** | **3.24ms** | 1.29ms | 0.5ms | |
686
+ | **WINDOW FUNCTION 1K** | **486.75ms** | 8.42ms | 2ms | |
687
+
688
+ ### Rust NAPI 加速引擎性能 (SIMD)
689
+
690
+ > ⚠️ **2026-10-27 独立评测修正(2026-10-28 部分已修复)**:下表数据来自 v1.32 时代的旧基准。独立评测实测发现:Rust 加速层多数路径未在生产代码接线(4/5 性能声称失效);评测同时暴露三处 AVX2 正确性 bug(utf8 批量编码、Float64 min/max 全 NaN、null bitmap ≥0x80),该三处已在 2026-10-28 修复并重建 `native/index.node`、相关 Native 路径已恢复。下表加速比仅供参考,不构成当前版本(v2.53.0)的性能承诺。
691
+ >
692
+ > 详见 [SIMD 优化报告](docs/simd/simd-final-optimization-report.md)
693
+
694
+ | 函数 | 数据量 | Rust Native | Pure JS | 加速比 | 适用场景 |
695
+ |------|--------|-------------|---------|--------|---------|
696
+ | **Int32 min/max** | 1,000 | 0.0006ms | 0.0269ms | **44.8x** | 聚合计算 |
697
+ | **Int32 min/max** | 10,000 | 0.0017ms | 0.0513ms | **30.2x** | 聚合计算 |
698
+ | **Float64 min/max** | 1,000 | 0.0014ms | 0.0256ms | **18.3x** | 聚合计算 |
699
+ | **Float64 求和** | 1,000,000 | 0.5ms | 8.0ms | **16.0x** | SUM/COUNT |
700
+ | **样本方差** | 100,000 | 0.05ms | 0.35ms | **7.0x** | STDDEV |
701
+ | **CRC32C 校验** | 1MB | 0.3ms | 1.5ms | **5.0x** | WAL 校验 |
702
+ | **Bloom Filter** | 10K 元素 | 0.2ms | 1.0ms | **5.0x** | 索引加速 |
703
+ | **L2 距离批量** | 10K×128维 | 2ms | 8ms | **4.0x** | 向量搜索 |
704
+
705
+ ### 不同数据量下的加速比变化
706
+
707
+ | 函数 | 100 | 1,000 | 10,000 | 100,000 | 1,000,000 |
708
+ |------|-----|-------|--------|---------|-----------|
709
+ | **Int32 min/max** | 1.0x | 12.0x | 20.0x | 20.5x | 5.1x |
710
+ | **Float64 min/max** | 1.0x | 8.3x | 10.1x | 2.6x | 2.5x |
711
+ | **Float64 求和** | 0.75x | 5.0x | 12.0x | 13.3x | 16.0x |
712
+ | **样本方差** | 1.3x | 10.0x | 10.0x | 10.8x | — |
713
+ | **标准差** | 1.0x | 7.5x | 1.6x | 0.99x | — |
714
+
715
+ **加速比变化规律**:
716
+ 1. **小数据量 (< 100)**:NAPI 调用开销占比高,加速不明显甚至负优化
717
+ 2. **中等数据量 (1K-10K)**:SIMD 并行优势显现,加速比达到峰值
718
+ 3. **大数据量 (> 100K)**:内存带宽成为瓶颈,加速比趋于稳定
719
+
720
+ ### 运行基准测试
721
+
722
+ ```bash
723
+ # DELETE/JOIN 性能基准测试
724
+ node test/performance/delete-join-benchmark.js
725
+
726
+ # SIMD 加速性能基准测试
727
+ node test/native/native-simd-benchmark.js
728
+ node test/native/native-simd-benchmark.js --size=1000000 --iterations=50
729
+
730
+ # Rust NAPI 自动切换回归测试
731
+ node test/native/native-full-regression.test.js
732
+
733
+ # SIMD 单元测试
734
+ node test/native/native-simd-unit.test.js
735
+ ```
736
+
737
+ ---
738
+
739
+ ## 版本历史
740
+
741
+ 查看 [CHANGELOG.md](CHANGELOG.md)(如不存在则以 git log 为准)。
742
+
743
+ ---
744
+
745
+ ## 许可
746
+
747
+ [MIT](LICENSE)