jsondb-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de84df565ca367ee562fe727f6d17ad1ff1a0678b907d0112e5cf81064049e90
+  data.tar.gz: 1b2e775b6b101f184e14347175a632d132fbb81c0d6ea3a9933575d63e4b09ce
+SHA512:
+  metadata.gz: d8006be3f0bf9c38f6c9b62e52491a2bdaa3254d5dd6c4b649a92c7c3807289af9910ca0b6786be2b8419ae30a4385adc2c55a361254f54c3c8a132f52b00072
+  data.tar.gz: f464b7f71a7e77023786060534816f85c660cf15372bc8b67a7da83b83d2830f4896d1214ba9b9755407eb7f98ef2e4e9ed55b422d9642df563be9fd33866391

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shiningray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+# jsondb-rb
+
+[![CI](https://github.com/ShiningRay/jsondb-rb/actions/workflows/ci.yml/badge.svg)](https://github.com/ShiningRay/jsondb-rb/actions/workflows/ci.yml)
+
+把一个 JSON 文件当数据库读写的 Ruby 库。零运行时依赖（纯标准库），MongoDB-lite 查询语法，落盘永远原子。
+
+> gem 名 `jsondb-rb`（rubygems 的 `jsondb` 已被 2014 年旧库占用）；require 路径与模块名不变：`require 'jsondb'` → `JsonDb`。
+
+```ruby
+require 'jsondb'
+
+db = JsonDb.open('app.json')
+users = db[:users]
+
+users.insert(name: 'Ann', age: 31, tags: %w[ruby db])
+users.insert_many([{ name: 'Bob', age: 17 }, { name: 'Cara', age: 45 }])
+
+users.where(age: { gte: 18 }).order(:name).limit(10).to_a
+users.where('profile.city' => 'SZ', age: (18..60)).count
+users.where('$or' => [{ vip: true }, { 'score' => { '$gte' => 90 } }]).pluck(:name)
+
+users.update_many({ age: { '$lt' => 18 } }, '$set' => { 'minor' => true })
+users.upsert({ name: 'Ann' }, '$inc' => { 'login_count' => 1 })
+
+db.transaction do
+  db[:orders].insert(user: 'Ann', total: 99)
+  db[:users].update_one({ name: 'Ann' }, '$push' => { 'orders' => 'o-1' })
+end # 一次落盘；块内抛错自动回滚
+
+db.close
+```
+
+数据文件长什么样，人可以直接编辑（改完下次读取自动重载）：
+
+```json
+{
+  "users": [
+    { "name": "Ann", "age": 31, "_id": "5f3a…" }
+  ]
+}
+```
+
+## 设计
+
+- **单文件**：顶层对象，键 = 集合名，值 = 文档数组。备份就是复制文件。
+- **内存权威**：读写都走内存；写操作后默认即时落盘（`autoflush: true`）。
+- **原子落盘**：同目录临时文件 → `fsync` → `rename` → 目录 `fsync`。任何时刻磁盘上只有完整的旧文件或新文件，绝无半截 JSON。
+- **`_id`**：文档唯一键；插入时缺省自动生成 24 位 hex。可自定义（`insert(_id: 'u1', …)`），不可变更。
+- **键与值的字符串化**：symbol 键/值入库时深度转为字符串（`name: :active` ↔ `"active"`），保证 JSON 往返一致；查询过滤器里的 symbol 自动同样处理。
+
+## 查询
+
+链式：`where(...).where(...)`（AND 叠加）`order` / `limit` / `offset` / `pluck` / `first` / `count` / `exists?`，惰性执行，枚举时取快照。
+
+字段名支持点路径，含数组下标：`'profile.city'`、`'tags.0'`。
+
+操作符支持两种写法：字符串 `'$gt'` 与裸符号 `gt:`（`age: { gte: 18 }`）。显式 `$` 前缀写错操作符名会抛错；裸符号不在操作符表内则按数据 Hash 等值匹配。
+
+| 过滤写法 | 含义 |
+|---|---|
+| `age: 31` | 等值 |
+| `age: { '$gt' => 18 }`（`$gte` `$lt` `$lte` 同理） | 比较；缺失/类型不合不匹配、不抛错 |
+| `age: (18..60)` | 区间（Range） |
+| `name: { '$ne' => 'Ann' }` | 不等（缺失字段也算匹配） |
+| `age: { '$in' => [18, 31] }` / `'$nin'` | 枚举（元素可为 Regexp） |
+| `active: { '$exists' => true }` | 键存在性（值为 false 也算存在） |
+| `name: { '$regex' => /^A/ }` | 正则（String 或 Regexp） |
+| `tags: { '$size' => 2 }` / `'$all' => [...]` | 数组长度 / 全包含 |
+| `age: { '$type' => 'integer' }` | JSON 类型（null/boolean/integer/float/string/array/object） |
+| `age: { '$not' => { '$gte' => 18 } }` | 字段级取反 |
+| `'$and' / '$or' / '$nor'` | 逻辑组合（空 `$or` 永不匹配） |
+| `name: /^A/`（直接 Regexp 值） | 等价 `$regex` |
+
+排序对混合类型安全（`false < true < 数值 < 字符串 < 数组 < 对象 < nil`，nil/缺失垫底；平键保持插入序）。`order(:name)`、`order(:age, :desc)`、`order(age: :desc, name: :asc)` 均可，多次调用逐键追加。
+
+## 更新
+
+| 写法 | 含义 |
+|---|---|
+| `update_one(f, { age: 32 })` | 裸 Hash = 按字段赋值（值整体替换） |
+| `'$set' => { 'a.b' => v }` | 点路径赋值，中间缺失自动补 `{}` |
+| `'$unset' => { 'a.b' => '' }`（或数组） | 删键 |
+| `'$inc' => { 'n' => 1 }` | 数值增减（缺失视 0；目标非数值抛错，整批不落地） |
+| `'$push' => { 'tags' => v }` / `{ '$each' => [...] }` | 追加数组元素 |
+| `'$pull' => { 'tags' => v }` | 删等值元素；Hash 值按子过滤器删 |
+
+`update_one` / `update_many`（批量）、`update(id, changes)`（按 `_id`）、`upsert(filter, changes)`（无则插：过滤条件 ⊕ 更新集合成文档）。操作符中途失败时该次调用全部不落地（先在副本上应用成功再写入）。
+
+删除：`delete(id)` / `delete_one(filter)` / `delete_many(filter)` / `clear!`；`db.drop(:name)` 连集合一起删。
+
+## 持久化与事务
+
+- `JsonDb.open(path, pretty: true, autoflush: true)`；`pretty: false` 出紧凑 JSON。
+- 批量写入：`JsonDb.open(path, autoflush: false)` 后手动 `db.flush`；或用 `db.transaction { … }`（块内禁即时落盘，正常结束一次落盘，抛错整体回滚到事务前）。
+- `db.close` 落盘并封存实例；`db.reload!` 丢弃内存改动强制重读。
+- 外部改动：无未落盘改动时，下次读取自动察觉（mtime+size）并重载——手编文件、多进程读都新鲜。本地有未落盘改动且文件又被他方改写时，打印一次警告，落盘以本地为准。
+
+## 并发语义（如实声明）
+
+- 单进程多线程：安全（Monitor 串行化，含 `fork` 前后语义）。
+- 跨进程：写经数据文件旁的 `<path>.lock` flock 串行化，落盘原子；**多进程并发写为文件级 last-write-wins，不合并**——两进程同时各自写不同文档，后落盘者覆盖整文件。写者之间靠 mtime 重载尽量累积对方改动，但读-改-写竞态窗口内的丢失不设防。需要强一致多写，请单写者或外部协调（这也是同类库 lowdb/TinyDB 的共同边界）。
+- 读永远一致：任何进程任何时刻读文件，只会看到完整的某一版。
+
+## 约束与边界
+
+- 文档只支持 JSON 原生类型（Hash/Array/String/Numeric/Boolean/nil）；Date/Time 等请自行转字符串。symbol 自动转字符串。
+- 无索引：每次查询全集合扫描。万级文档以下舒适，十万级请上真数据库。
+- `$elemMatch`、投影（projection）、聚合：暂无，见需再加。
+
+## 安装
+
+```ruby
+# Gemfile（gem 名 jsondb-rb，require 路径 jsondb）
+gem 'jsondb-rb', '~> 0.1'
+```
+
+```sh
+gem install jsondb-rb   # 然后 require 'jsondb'
+```
+
+发版走 git tag（`v*`）触发 [release.yml](.github/workflows/release.yml)，经 rubygems OIDC trusted publishing 推送。
+
+## 测试
+
+```sh
+rake test   # 44 例：CRUD / 查询操作符 / 持久化 / 事务 / 多线程 / 多进程 fork 并发
+```
+
+Ruby >= 3.1，纯标准库。

data/lib/jsondb/atomic_file.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module JsonDb
+  # 原子写：同目录临时文件 + fsync + rename + 目录 fsync。
+  # 读者只会看到完整的旧文件或新文件，绝无半截 JSON。
+  module AtomicFile
+    module_function
+
+    # @param path [String] 目标文件
+    # @param content [String] 完整文件内容（UTF-8）
+    def write(path, content)
+      directory = File.dirname(path)
+      FileUtils.mkdir_p(directory)
+      Tempfile.create(['.jsondb-', '.tmp'], directory) do |file|
+        file.binmode
+        file.write(content)
+        file.flush
+        file.fsync
+        File.rename(file.path, path)
+      end
+      File.open(directory, File::RDONLY, &:fsync)
+      path
+    end
+  end
+end

data/lib/jsondb/collection.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module JsonDb
+  # 文档集合：内存数组 + 经 DB 落盘。所有文档键为字符串、带唯一 _id。
+  class Collection
+    include Enumerable
+
+    attr_reader :name
+
+    # @param db [DB] 宿主库
+    # @param name [String, Symbol]
+    def initialize(db, name)
+      raise Error, '集合名不能为空' if name.to_s.empty?
+
+      @db = db
+      @name = name.to_s
+    end
+
+    def insert(doc)
+      insert_many([doc]).first
+    end
+
+    # @return [Array<Hash>] 实际入库的文档（字符串键、含 _id）
+    def insert_many(docs)
+      raise Error, 'insert_many 需要数组' unless docs.is_a?(Array)
+
+      stored = docs.map { |doc| prepare(doc) }
+      @db.mutate do |docs_of|
+        list = docs_of[@name] ||= []
+        # 先全量校验（含批内重复）再落地：失败时一条都不进
+        ids = stored.map { |d| d['_id'] }
+        if ids.uniq.size != ids.size
+          raise DuplicateIdError, "批内 _id 重复（集合 #{@name}）：#{(ids - ids.uniq).inspect}"
+        end
+
+        clash = ids.find { |id| any_id?(list, id) }
+        raise DuplicateIdError, "_id 重复: #{clash.inspect}（集合 #{@name}）" if clash
+
+        list.concat(stored)
+      end
+      stored.map { |d| Path.deep_dup(d) }
+    end
+
+    # 按 _id 取文档；未命中返回 nil
+    def find(id)
+      docs.find { |d| d['_id'].to_s == id.to_s }
+    end
+
+    def find!(id)
+      find(id) || (raise Error, "未找到 _id=#{id.inspect}（集合 #{@name}）")
+    end
+
+    def where(filter = {})
+      Query.new(self, filter)
+    end
+
+    def each(&block)
+      return to_enum(:each) unless block
+
+      docs.each(&block)
+    end
+
+    def count(filter = nil)
+      filter ? where(filter).count : docs.size
+    end
+
+    alias size count
+
+    # 更新首个匹配。changes 为裸 Hash（按 $set 处理）或操作符 Hash。
+    # @return [Hash, nil] 更新后的文档；未命中返回 nil
+    def update_one(filter, changes)
+      update_docs(filter, changes, limit: 1).first
+    end
+
+    # @return [Integer] 更新条数
+    def update_many(filter, changes)
+      update_docs(filter, changes, limit: nil).size
+    end
+
+    def update(id, changes)
+      update_one({ '_id' => id.to_s }, changes)
+    end
+
+    # 无匹配则插入（过滤条件与更新集合成文档），有匹配则更新首条
+    def upsert(filter, changes)
+      existing = where(filter).first
+      return update_one(filter, changes) if existing
+
+      insert(Updater.upsert_doc(filter, changes))
+    end
+
+    # @return [Integer] 删除条数
+    def delete_one(filter)
+      delete_docs(filter, limit: 1)
+    end
+
+    def delete_many(filter)
+      delete_docs(filter, limit: nil)
+    end
+
+    def delete(id)
+      delete_one({ '_id' => id.to_s })
+    end
+
+    # 清空集合（集合保留）
+    def clear!
+      @db.mutate { |docs_of| docs_of[@name].clear }
+      self
+    end
+
+    def empty?
+      docs.empty?
+    end
+
+    # 快照：外部改动会在取快照前被察觉并重载（无本地未落盘改动时）
+    # @return [Array<Hash>] 文档数组副本（浅拷贝，元素为共享文档——勿就地修改）
+    def docs
+      @db.docs_snapshot(@name)
+    end
+
+    def to_s
+      "#<JsonDb::Collection #{@name} size=#{size}>"
+    end
+    alias inspect to_s
+
+    private
+
+    def prepare(doc)
+      raise Error, '文档必须是 Hash' unless doc.is_a?(Hash)
+
+      stored = Path.stringify(doc)
+      stored['_id'] ||= new_id
+      stored['_id'] = stored['_id'].to_s
+      raise Error, '_id 不能为空' if stored['_id'].empty?
+
+      stored
+    end
+
+    def new_id
+      SecureRandom.hex(12)
+    end
+
+    def any_id?(list, id)
+      list.any? { |d| d['_id'] == id }
+    end
+
+    def update_docs(filter, changes, limit:)
+      updated = []
+      @db.mutate do |docs_of|
+        list = docs_of[@name]
+        matched = list.select { |doc| Matcher.match?(doc, filter) }
+        matched = matched.first(1) if limit == 1
+        # 先在副本上全部应用成功，再换入：操作符中途抛错不会留下半改状态
+        updated = matched.map { |doc| Updater.apply!(Path.deep_dup(doc), changes) }
+        matched.zip(updated).each { |doc, new_doc| doc.replace(new_doc) }
+        updated.map! { |d| Path.deep_dup(d) }
+      end
+      updated
+    end
+
+    def delete_docs(filter, limit:)
+      removed = []
+      @db.mutate do |docs_of|
+        list = docs_of[@name]
+        list.reject! do |doc|
+          hit = Matcher.match?(doc, filter) && (limit.nil? || removed.size < limit)
+          removed << doc if hit
+          hit
+        end
+      end
+      removed.size
+    end
+  end
+end

data/lib/jsondb/db.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'monitor'
+require 'fileutils'
+
+module JsonDb
+  # JSON 文件数据库。
+  #
+  # 文件格式：顶层对象，键=集合名，值=文档数组。人可直接阅读编辑。
+  # 持久化：内存为权威，写操作后原子落盘（同目录临时文件+fsync+rename）。
+  # 并发：进程内 Monitor 串行化；跨进程写经 .lock 文件 flock 串行化，
+  #       读者只见完整文件；多进程并发写为文件级 last-write-wins（无合并）。
+  class DB
+    attr_reader :path
+
+    # @param path [String, Pathname] 数据文件路径（不存在则新建）
+    # @param pretty [Boolean] 落盘是否缩进美化（默认开，便于人读；大数据可关）
+    # @param autoflush [Boolean] 每次写操作后立即落盘（默认开；批量写可关后手动 flush）
+    def initialize(path = 'jsondb.json', pretty: true, autoflush: true)
+      @path = File.expand_path(path.to_s)
+      @pretty = pretty
+      @autoflush = autoflush
+      @monitor = Monitor.new
+      @collections = {}
+      @dirty = false
+      @in_transaction = false
+      @loaded_stamp = nil
+      @warned_conflict = false
+      @closed = false
+      load
+    end
+
+    # 取集合（不物化：真正出现于 collections 要等首个文档写入）
+    def [](name)
+      ensure_open
+      name = name.to_s
+      raise Error, '集合名不能为空' if name.empty?
+
+      Collection.new(self, name)
+    end
+
+    alias collection []
+
+    def collection?(name)
+      ensure_open
+      @monitor.synchronize { @collections.key?(name.to_s) }
+    end
+
+    # @return [Array<String>] 集合名（排序）
+    def collections
+      ensure_open
+      @monitor.synchronize { refresh_if_clean!; @collections.keys.sort }
+    end
+
+    # 删除整个集合（含文档）
+    # @return [Boolean] 是否删除了集合
+    def drop(name)
+      ensure_open
+      mutate { |cols| !cols.delete(name.to_s).nil? }
+    end
+
+    # @return [Integer] 全库文档总数
+    def size
+      ensure_open
+      @monitor.synchronize do
+        refresh_if_clean!
+        @collections.values.sum(&:size)
+      end
+    end
+
+    # 强制从磁盘重载，丢弃内存中未落盘的改动
+    def reload!
+      ensure_open
+      @monitor.synchronize { load }
+      self
+    end
+
+    # 把内存改动落盘；无改动时为 no-op
+    # @return [Boolean] 是否真的写了文件
+    def flush
+      ensure_open
+      @monitor.synchronize do
+        return false unless @dirty
+
+        write_file
+        true
+      end
+    end
+
+    # 事务：块内 autoflush 关闭，异常回滚到事务前状态，正常结束统一落盘。
+    # 嵌套事务抛错。返回块值。
+    def transaction
+      raise Error, '不能嵌套事务' if @in_transaction
+
+      @monitor.synchronize do
+        ensure_open
+        refresh_if_clean!
+        snapshot = Path.deep_dup(@collections)
+        prev_autoflush = @autoflush
+        @autoflush = false
+        @in_transaction = true
+        begin
+          result = yield self
+          flush
+          result
+        rescue Exception => e # rubocop:disable Lint/RescueException 回滚须覆盖一切退出路径
+          @collections = snapshot
+          @dirty = true # 保守置脏：快照可能含事务前的未落盘改动
+          raise e
+        ensure
+          @autoflush = prev_autoflush
+          @in_transaction = false
+        end
+      end
+    end
+
+    # 落盘并关闭（此后本实例不可再用）
+    def close
+      flush
+      @monitor.synchronize { @closed = true }
+      nil
+    end
+
+    def closed?
+      @closed
+    end
+
+    def to_s
+      "#<JsonDb::DB #{path} collections=#{collections.size} size=#{size}>"
+    end
+    alias inspect to_s
+
+    # ---- 内部：Collection 经此读写，保证锁纪律 ----
+
+    # 供 Collection 读快照：先察觉外部改动（无未落盘改动时自动重载）
+    def docs_snapshot(name)
+      ensure_open
+      @monitor.synchronize do
+        refresh_if_clean!
+        (@collections[name.to_s] || []).dup
+      end
+    end
+
+    # 供 Collection 写：块内拿到活集合表（键→数组），块返回后置脏并按需落盘
+    def mutate
+      ensure_open
+      @monitor.synchronize do
+        warn_conflict_once!
+        refresh_if_clean!
+        @dirty = true # 先置脏：块中途抛错时已发生的改动不会被静默丢弃
+        result = yield @collections
+        flush if @autoflush && !@in_transaction
+        result
+      end
+    end
+
+    # 本地有未落盘改动而文件又被他方改写：落盘将以本地为准（last-write-wins），只警一次
+    def warn_conflict_once!
+      return unless @dirty && !@warned_conflict && disk_stamp != @loaded_stamp
+
+      @warned_conflict = true
+      warn '[jsondb] 外部改动与本地未落盘改动并存，落盘将以本地为准（last-write-wins）'
+      nil
+    end
+
+    private
+
+    def load
+      if File.file?(@path)
+        parsed =
+          begin
+            JSON.parse(File.read(@path))
+          rescue JSON::ParserError => e
+            raise Error, "数据文件损坏（非合法 JSON）: #{@path}：#{e.message}"
+          end
+        unless parsed.is_a?(Hash) && parsed.values.all? { |v| v.is_a?(Array) }
+          raise Error, "数据文件结构不符：顶层须为 {集合名: [文档, ...]}：#{@path}"
+        end
+        @collections = parsed
+      else
+        @collections = {}
+      end
+      @dirty = false
+      @loaded_stamp = disk_stamp
+      nil
+    end
+
+    def write_file
+      content = @pretty ? JSON.pretty_generate(@collections) : JSON.generate(@collections)
+      # 锁文件先于数据文件创建：先确保父目录存在（首写时目录可能尚无）
+      FileUtils.mkdir_p(File.dirname(@path))
+      # 每次落盘重开锁文件：fork 出的子进程不共享文件描述，flock 才真正互斥
+      File.open("#{@path}.lock", File::RDWR | File::CREAT, 0o644) do |lock|
+        lock.flock(File::LOCK_EX)
+        AtomicFile.write(@path, content)
+      end
+      @loaded_stamp = disk_stamp
+      @dirty = false
+      nil
+    end
+
+    def refresh_if_clean!
+      return if @dirty
+
+      load if disk_stamp != @loaded_stamp
+    end
+
+    # [mtime, size] 元组：File::Stat 未定义 ==，直接比对象永远不等
+    def disk_stamp
+      stat = File.stat(@path)
+      [stat.mtime.to_f, stat.size]
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def ensure_open
+      raise Error, '库已关闭' if @closed
+    end
+  end
+end

data/lib/jsondb/matcher.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module JsonDb
+  # 过滤器匹配：MongoDB-lite 语义。
+  #   顶层多键隐含 AND；'$and'/'$or'/'$nor'/'$not' 组合；
+  #   字段值 Hash 全 $ 键 → 操作符映射；Range → gte+lte；Regexp → regex。
+  module Matcher
+    LOGICAL = %w[$and $or $nor $not].freeze
+    OPERATORS = %w[$eq $ne $gt $gte $lt $lte $in $nin $exists $regex $size $all $type].freeze
+
+    module_function
+
+    def match?(doc, filter)
+      filter = Path.stringify(filter)
+      filter.all? do |key, cond|
+        case key
+        when '$and' then cond.all? { |sub| match?(doc, sub) }
+        when '$or'  then !cond.empty? && cond.any? { |sub| match?(doc, sub) }
+        when '$nor' then cond.none? { |sub| match?(doc, sub) }
+        when '$not' then !match?(doc, cond)
+        else match_field(doc, key, cond)
+        end
+      end
+    end
+
+    def match_field(doc, field, cond)
+      exists = Path.exists?(doc, field)
+      value = Path.get(doc, field)
+
+      case cond
+      when Hash
+        return false if cond.empty? # {} 按等值处理：字段须恰为空 Hash
+
+        ops = operator_map(cond)
+        if ops
+          ops.all? { |op, arg| apply_operator(doc, field, exists, value, op, arg) }
+        else
+          exists && value == cond # 普通嵌套 Hash：整体等值
+        end
+      when Range  then exists && cover_if_comparable(value, cond)
+      when Regexp then exists && value.is_a?(String) && cond.match?(value)
+      else exists && value == cond
+      end
+    end
+
+    # 值位 Hash 的键全为已知操作符才按操作符处理；支持 '$gt' 与裸符号 :gt 两种写法。
+    # 显式 $ 前缀但未知 → 报错（打字保护）；裸符号未知 → 返回 nil 按等值匹配（数据型嵌套 Hash）。
+    def operator_map(cond)
+      normalized = {}
+      cond.each_key do |key|
+        name = key.to_s
+        explicit = name.start_with?('$')
+        name = "$#{name}" unless explicit
+        if OPERATORS.include?(name) || name == '$not'
+          normalized[name] = cond[key]
+        elsif explicit
+          raise Error, "不支持的操作符: #{name.inspect}"
+        else
+          return nil
+        end
+      end
+      normalized
+    end
+
+    def apply_operator(doc, field, exists, value, op, arg)
+      case op
+      when '$eq'    then exists && value == Path.stringify(arg)
+      when '$ne'    then !exists || value != Path.stringify(arg)
+      when '$gt'    then exists && ordered?(value, arg) { |c| c > 0 }
+      when '$gte'   then exists && ordered?(value, arg) { |c| c >= 0 }
+      when '$lt'    then exists && ordered?(value, arg) { |c| c < 0 }
+      when '$lte'   then exists && ordered?(value, arg) { |c| c <= 0 }
+      when '$in'    then arg.any? { |v| member?(value, exists, v) }
+      when '$nin'   then arg.none? { |v| member?(value, exists, v) }
+      when '$exists' then !!exists == truthy(arg)
+      when '$regex' then regex_match(exists, value, arg)
+      when '$size'  then value.is_a?(Array) && value.size == arg
+      when '$all'   then value.is_a?(Array) && arg.all? { |v| value.include?(Path.stringify(v)) }
+      when '$type'  then exists && json_type(value) == arg.to_s
+      when '$not'   then !match_field(doc, field, arg)
+      else raise Error, "不支持的操作符: #{op.inspect}（字段 #{field.inspect}）"
+      end
+    end
+
+    def member?(value, exists, candidate)
+      return false unless exists
+
+      candidate = Path.stringify(candidate)
+      if candidate.is_a?(Regexp)
+        value.is_a?(String) && candidate.match?(value)
+      else
+        value == candidate
+      end
+    end
+
+    # Range 只对 Numeric/String 生效；类型不合返回 false 而非抛错
+    def cover_if_comparable(value, range)
+      return false unless range_coverable?(value, range)
+
+      range.cover?(value)
+    end
+
+    def range_coverable?(value, range)
+      (value.is_a?(Numeric) && range.first.is_a?(Numeric)) ||
+        (value.is_a?(String) && range.first.is_a?(String))
+    end
+
+    # 同族（同为 Numeric 或同为 String）才可比；否则 nil（判定不匹配）
+    def compare_if_same_family(a, b)
+      return a <=> b if a.is_a?(Numeric) && b.is_a?(Numeric)
+      return a <=> b if a.is_a?(String) && b.is_a?(String)
+
+      nil
+    end
+
+    def ordered?(value, arg)
+      cmp = compare_if_same_family(value, arg)
+      cmp && yield(cmp)
+    end
+
+    def regex_match(exists, value, arg)
+      return false unless exists && value.is_a?(String)
+
+      pattern = arg.is_a?(Regexp) ? arg : Regexp.new(arg.to_s)
+      pattern.match?(value)
+    end
+
+    def truthy(arg)
+      !(arg.nil? || arg == false)
+    end
+
+    # JSON 类型名（$type 用）
+    def json_type(value)
+      case value
+      when NilClass   then 'null'
+      when true, false then 'boolean'
+      when Integer    then 'integer'
+      when Float      then 'float'
+      when String     then 'string'
+      when Array      then 'array'
+      when Hash       then 'object'
+      else raise Error, "非 JSON 类型: #{value.class}"
+      end
+    end
+  end
+end

data/lib/jsondb/path.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module JsonDb
+  # 点路径读写：'a.b.0.c' 在嵌套 Hash/Array 上取值、赋值、删除。
+  # 段全以字符串存放；纯数字段视为数组下标（仅对已存在的 Array 生效）。
+  module Path
+    module_function
+
+    # 'a.b.c' → ['a', 'b', 'c']
+    def segments(path)
+      path.to_s.split('.')
+    end
+
+    def exists?(doc, path)
+      value = doc
+      segments(path).each do |seg|
+        if value.is_a?(Array)
+          return false unless index?(seg, value)
+
+          value = value[seg.to_i]
+        elsif value.is_a?(Hash)
+          return false unless value.key?(seg)
+
+          value = value[seg]
+        else
+          return false
+        end
+      end
+      true
+    end
+
+    # @return 命中值；不存在返回 nil（与存 nil 无法区分，判存在用 exists?）
+    def get(doc, path)
+      value = doc
+      segments(path).each do |seg|
+        return nil unless container?(value)
+        return nil if value.is_a?(Array) && !index?(seg, value)
+
+        value = value.is_a?(Array) ? value[seg.to_i] : value[seg]
+      end
+      value
+    end
+
+    # 赋值。中间缺失的 Hash 段自动补 {}；数组下标只接受已存在位置或末尾追加。
+    def set(doc, path, value)
+      segs = segments(path)
+      raise Error, "空路径: #{path.inspect}" if segs.empty?
+
+      target = segs[0..-2].inject(doc) do |node, seg|
+        next_node = node.is_a?(Array) ? node[seg.to_i] : node[seg]
+        if next_node.nil?
+          raise Error, "路径中断于 #{seg.inspect}：不可补容器" if node.is_a?(Array)
+
+          node[seg] = {}
+          next_node = node[seg]
+        end
+        raise Error, "路径中断于 #{seg.inspect}：非容器" unless container?(next_node)
+
+        next_node
+      end
+      last = segs.last
+      if target.is_a?(Array)
+        idx = last.to_i
+        raise Error, "数组下标越界: #{path}" unless idx <= target.size
+
+        idx == target.size ? target.push(value) : target[idx] = value
+      else
+        target[last] = value
+      end
+      value
+    end
+
+    # 删除路径值；路径不存在则静默返回 nil。
+    def delete(doc, path)
+      segs = segments(path)
+      return nil if segs.empty?
+
+      parent = doc
+      segs[0..-2].each do |seg|
+        return nil unless container?(parent)
+        return nil if parent.is_a?(Array) && !index?(seg, parent)
+
+        parent = parent.is_a?(Array) ? parent[seg.to_i] : parent[seg]
+      end
+      return nil unless container?(parent)
+
+      last = segs.last
+      if parent.is_a?(Array)
+        idx = last.to_i
+        idx < parent.size ? parent.delete_at(idx) : nil
+      else
+        parent.delete(last)
+      end
+    end
+
+    # 深度字符串化：入库前把 symbol key/value 统一为字符串，保证 JSON 往返一致
+    def stringify(value)
+      case value
+      when Hash   then value.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify(v) }
+      when Array  then value.map { |v| stringify(v) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+
+    # JSON 原生类型深拷贝（文档只含 JSON 类型，Marshal 安全且快）
+    def deep_dup(value)
+      Marshal.load(Marshal.dump(value))
+    end
+
+    def container?(value)
+      value.is_a?(Hash) || value.is_a?(Array)
+    end
+
+    def index?(seg, array)
+      /\A\d+\z/.match?(seg) && seg.to_i < array.size
+    end
+  end
+end

data/lib/jsondb/query.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module JsonDb
+  # 链式查询：where(...).order(...).limit(n).offset(n) → 惰性，枚举时取快照执行。
+  # 每次 where 追加 AND 条件；order 可多次调用逐键追加；结果 Enumerable。
+  class Query
+    include Enumerable
+
+    # @param collection [Collection]
+    # @param filter [Hash]
+    def initialize(collection, filter = {})
+      @collection = collection
+      @filters = [filter]
+      @order_specs = []
+      @limit_value = nil
+      @offset_value = 0
+    end
+
+    def where(filter)
+      @filters << filter
+      self
+    end
+
+    # order(:name) → 升序；order(age: :desc, name: :asc) 多键；order(:age, :desc) 单键带方向
+    def order(*specs)
+      spec = normalize_order_spec(specs)
+      spec.each { |k, dir| @order_specs << [k.to_s, dir] }
+      self
+    end
+
+    def normalize_order_spec(specs)
+      case specs.size
+      when 1
+        specs.first.is_a?(Hash) ? specs.first : { specs.first => :asc }
+      when 2
+        raise ArgumentError, "order 参数不合法: #{specs.inspect}" unless %i[asc desc].include?(specs.last)
+
+        { specs.first => specs.last }
+      else
+        raise ArgumentError, "order 参数不合法: #{specs.inspect}"
+      end
+    end
+
+    def limit(n)
+      @limit_value = Integer(n)
+      self
+    end
+
+    def offset(n)
+      @offset_value = Integer(n)
+      self
+    end
+
+    def each(&block)
+      return to_enum(:each) unless block
+
+      execute.each(&block)
+    end
+
+    def to_a
+      execute
+    end
+
+    def first
+      saved = @limit_value
+      @limit_value = 1
+      begin
+        execute.first
+      ensure
+        @limit_value = saved
+      end
+    end
+
+    def count
+      execute.size
+    end
+
+    def exists?
+      !execute.empty?
+    end
+
+    # pluck(:name) → [值]；pluck(:a, :b) → [[a, b], ...]；支持点路径
+    def pluck(*keys)
+      keys = keys.map(&:to_s)
+      rows = execute
+      if keys.size == 1
+        rows.map { |d| Path.get(d, keys.first) }
+      else
+        rows.map { |d| keys.map { |k| Path.get(d, k) } }
+      end
+    end
+
+    private
+
+    # 枚举时执行：集合快照 → 过滤 → 排序 → offset → limit
+    def execute
+      docs = @collection.docs
+      @filters.each do |filter|
+        docs = docs.select { |d| Matcher.match?(d, filter) }
+      end
+      docs = sort(docs) unless @order_specs.empty?
+      docs = docs[@offset_value..] || [] unless @offset_value.zero?
+      docs = docs[0, @limit_value] if @limit_value
+      docs
+    end
+
+    def sort(docs)
+      indexed = docs.each_with_index.to_a
+      indexed.sort! do |(a, ai), (b, bi)|
+        cmp = 0
+        @order_specs.each do |key, dir|
+          cmp = compare(Path.get(a, key), Path.get(b, key))
+          cmp = -cmp if dir.to_s.start_with?('desc', '-')
+          break unless cmp.zero?
+        end
+        # 稳定排序：键全等时保持原序（插入序）
+        cmp.zero? ? ai <=> bi : cmp
+      end
+      indexed.map!(&:first)
+    end
+
+    # 跨类型安全比较：false < true < 数值 < 字符串 < 数组 < 对象 < nil（缺失垫底，升序在末）；
+    # 同族（数值/字符串/数组）深入比较，避免 String <=> Integer 抛错。
+    TYPE_RANK = { FalseClass => 0, TrueClass => 1, Numeric => 3, String => 4, Array => 5, Hash => 6, NilClass => 7 }.freeze
+
+    def compare(a, b)
+      ra = rank(a)
+      rb = rank(b)
+      return ra <=> rb unless ra == rb
+
+      case a
+      when Numeric, String then a <=> b
+      when Array
+        a.zip(b).each do |x, y|
+          c = compare(x, y)
+          return c unless c.zero?
+        end
+        a.size <=> b.size
+      else 0 # true/false/nil/Hash 同族视为相等档
+      end
+    end
+
+    def rank(value)
+      TYPE_RANK.each do |klass, r|
+        return r if value.is_a?(klass)
+      end
+      TYPE_RANK.size
+    end
+  end
+end

data/lib/jsondb/updater.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module JsonDb
+  # 更新操作符：$set/$unset/$inc/$push/$pull；裸 Hash 视为顶层 $set。
+  # 字段名支持点路径；_id 不可变更（同值改写视为合法）。
+  module Updater
+    OPERATORS = %w[$set $unset $inc $push $pull].freeze
+
+    module_function
+
+    # 就地修改 doc（调用方负责传副本），返回 doc。
+    def apply!(doc, changes)
+      changes = Path.stringify(changes)
+      plain, ops = partition(changes)
+
+      plain.each { |k, v| guard_id!(doc, k, v); Path.set(doc, k, v) }
+      ops.each_key { |op| apply_operator!(doc, op, changes[op]) }
+      doc
+    end
+
+    def partition(changes)
+      plain = {}
+      ops = {}
+      changes.each do |k, v|
+        if k.to_s.start_with?('$')
+          ops[k.to_s] = v
+        else
+          plain[k.to_s] = v
+        end
+      end
+      [plain, ops]
+    end
+
+    def apply_operator!(doc, op, spec)
+      case op
+      when '$set'
+        spec.each { |k, v| guard_id!(doc, k, v); Path.set(doc, k, v) }
+      when '$unset'
+        keys(spec).each { |k| guard_id!(doc, k, nil); Path.delete(doc, k) }
+      when '$inc'
+        spec.each do |k, delta|
+          raise Error, "$inc 的值必须是数值: #{delta.inspect}" unless delta.is_a?(Numeric)
+
+          current = Path.get(doc, k) || 0
+          raise Error, "$inc 目标当前非数值: #{k.inspect}=#{current.inspect}" unless current.is_a?(Numeric)
+
+          guard_id!(doc, k, nil)
+          Path.set(doc, k, current + delta)
+        end
+      when '$push'
+        spec.each do |k, v|
+          values = v.is_a?(Hash) && v.key?('$each') ? v['$each'] : [v]
+          current = Path.get(doc, k)
+          current = Path.set(doc, k, []) if current.nil?
+          raise Error, "$push 目标当前非数组: #{k.inspect}=#{current.inspect}" unless current.is_a?(Array)
+
+          current.concat(values.map { |e| Path.stringify(e) })
+        end
+      when '$pull'
+        spec.each do |k, v|
+          current = Path.get(doc, k)
+          next unless current.is_a?(Array)
+
+          removed = current.reject { |el| pull_match?(el, v) }
+          current.replace(removed)
+        end
+      else
+        raise Error, "不支持的更新操作符: #{op.inspect}"
+      end
+    end
+
+    def keys(spec)
+      case spec
+      when Hash then spec.keys
+      when Array then spec
+      else raise Error, "$unset 需要 Hash 或 Array: #{spec.inspect}"
+      end
+    end
+
+    # $pull：标量按等值删；Hash 视为子过滤器（含 $ 键走操作符，否则字段等值）
+    def pull_match?(element, spec)
+      spec = Path.stringify(spec)
+      if element.is_a?(Hash) && spec.is_a?(Hash)
+        Matcher.match?(element, spec)
+      else
+        element == spec
+      end
+    end
+
+    # upsert 用的文档合成：过滤条件深度合并更新集（更新覆盖过滤）
+    def upsert_doc(filter, changes)
+      plain, ops = partition(Path.stringify(changes))
+      base = Path.stringify(filter).reject { |k, _| k.to_s.start_with?('$') }
+      merged = deep_merge(base, plain)
+      deep_merge(merged, ops['$set'] || {})
+    end
+
+    def deep_merge(base, extra)
+      extra.each_with_object(Path.deep_dup(base)) do |(k, v), acc|
+        if acc[k].is_a?(Hash) && v.is_a?(Hash)
+          acc[k] = deep_merge(acc[k], v)
+        else
+          acc[k] = v
+        end
+      end
+    end
+
+    def guard_id!(doc, key, new_value)
+      return unless key.to_s == '_id' && Path.exists?(doc, '_id')
+
+      raise Error, '_id 不可变更' unless new_value.nil? || new_value.to_s == doc['_id'].to_s
+    end
+  end
+end

data/lib/jsondb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JsonDb
+  VERSION = '0.1.0'
+end

data/lib/jsondb.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'jsondb/version'
+require_relative 'jsondb/atomic_file'
+require_relative 'jsondb/path'
+require_relative 'jsondb/matcher'
+require_relative 'jsondb/updater'
+require_relative 'jsondb/query'
+require_relative 'jsondb/collection'
+require_relative 'jsondb/db'
+
+# jsondb：把一个 JSON 文件当数据库读写的零依赖 Ruby 库。
+#
+#   db = JsonDb.open('app.json')
+#   users = db[:users]
+#   users.insert(name: 'Ann', age: 31)
+#   users.where(age: { gte: 18 }).order(:name).limit(10).to_a
+#   db.close
+module JsonDb
+  class Error < StandardError; end
+  class DuplicateIdError < Error; end
+
+  # @see DB#initialize
+  def self.open(path = 'jsondb.json', **options, &block)
+    db = DB.new(path, **options)
+    return db unless block
+
+    begin
+      block.call(db)
+    ensure
+      db.close
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: jsondb-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- shiningray
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: jsondb 将单个 JSON 文件作为嵌入式文档数据库：集合/文档 CRUD、点路径与查询操作符（$gt/$in/$regex/$or...）、链式
+  where/order/limit、更新操作符（$set/$inc/$push/$pull）、事务与原子落盘。纯 Ruby 标准库，无运行时依赖。
+email:
+- shiningray@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jsondb.rb
+- lib/jsondb/atomic_file.rb
+- lib/jsondb/collection.rb
+- lib/jsondb/db.rb
+- lib/jsondb/matcher.rb
+- lib/jsondb/path.rb
+- lib/jsondb/query.rb
+- lib/jsondb/updater.rb
+- lib/jsondb/version.rb
+homepage: https://github.com/ShiningRay/jsondb-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ShiningRay/jsondb-rb
+  source_code_uri: https://github.com/ShiningRay/jsondb-rb
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 把一个 JSON 文件当数据库读写（零依赖、MongoDB-lite 查询）
+test_files: []