lutaml-store 0.2.1 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c26211ca36caae48ef419c2feb670e6d35ddfb958b97b27eb04173c16eaa804
-  data.tar.gz: '06953ee0ec088797069476ccd0a2595aaae24b71fc295b3882ac628464b53da0'
+  metadata.gz: b6093f17ea0bca9240b608835a29b8f060a0c8c41be950e93fc0713e8c1b9444
+  data.tar.gz: f0f9ee8ace22fa22ec62408425ba7fa479648c57158c92967bc8e235fd037285
 SHA512:
-  metadata.gz: ac429b0436457ac91e52d18290c407598529d041294911c652a33fda075b4f24373965aea422568e85bcfa68e978a64fb4dc45b642fb9034555869a597ccb161
-  data.tar.gz: fefac8e5929d619716a9cf890601928fb52738b3ecb5d6a861a90d7d28db7902624108a8d2054a230ea4810291001690455777e0cbcebaa912fd9c8f67f11591
+  metadata.gz: 97a8aa5dc0d52617b1f4d97bd8378664eead01e299410d8dd506b775be23d69616008cde2e053b6a649819726048afdd2b227a455979630b2f07d04e76deed6d
+  data.tar.gz: b80834cd232f87d378c0a3a5f7ea17ef2c7ea2d68103d890756eabb2f2c85e20e1b1f193ec64cd0198fdb4235c0ff68ca6de87e788b7aabaa26b49a081e2023e

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-06-05 04:23:39 UTC using RuboCop version 1.87.0.
+# on 2026-06-10 09:02:53 UTC using RuboCop version 1.87.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,54 +11,63 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'lutaml-store.gemspec'
 
-# Offense count: 29
+# Offense count: 38
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
   Max: 112
 
-# Offense count: 50
+# Offense count: 63
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 387
 
-# Offense count: 16
+# Offense count: 17
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 379
+  Max: 516
 
-# Offense count: 9
+# Offense count: 15
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 11
+  Max: 13
 
-# Offense count: 80
+# Offense count: 89
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 84
 
-# Offense count: 5
+# Offense count: 6
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 8
 
-# Offense count: 5
+# Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 11
+  Max: 14
 
 # Offense count: 1
 Naming/AccessorMethodName:
   Exclude:
     - 'lib/lutaml/store/adapter/sqlite.rb'
 
-# Offense count: 3
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyleForLeadingUnderscores.
+# SupportedStylesForLeadingUnderscores: disallowed, required, optional
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - 'lib/lutaml/store/query.rb'
+
+# Offense count: 4
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
   Exclude:
     - 'demo/vcard_models.rb'
     - 'demo/vcard_store_demo.rb'
+    - 'lib/lutaml/store/adapter/sqlite.rb'
 
 # Offense count: 1
 # Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
@@ -84,7 +93,7 @@ Security/MarshalLoad:
   Exclude:
     - 'lib/lutaml/store/format/marshal_format.rb'
 
-# Offense count: 35
+# Offense count: 51
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Enabled: false

data/CLAUDE.md

@@ -28,30 +28,43 @@ This is a Ruby gem (`lutaml-store`) providing a store-centric database-style API
 
 | Class | Role |
 |---|---|
-| `DatabaseStore` | High-level CRUD with model registry, composite models, polymorphism |
+| `DatabaseStore` | High-level CRUD with model registry, composite models, polymorphism, file I/O |
 | `BasicStore` | Low-level key-value store with optional cache/monitor/events |
 | `CacheStore` | TTL-aware cache store extending `BasicStore` |
+| `PackageStore` | Structured multi-model packages with directory/ZIP transport |
+| `PackageDefinition` | Declarative schema for package structure (models, assets, metadata) |
 | `ModelRegistry` / `ModelRegistration` | Register models with their key fields and polymorphic config |
 | `CompositeModelHandler` | Stores nested registered models independently, restores references |
 | `AttributeUpdater` | Processes updates including dot-notation paths and block-based updates |
-| `ModelSerializer` | Single point of serialization/deserialization for Lutaml::Model objects |
-| `Config` | Parses and validates store configuration (adapter, cache, monitoring, compression) |
+| `ModelSerializer` | Hash-based serialization/deserialization for key-value storage |
+| `FormatSerializer` | Bridges any Format handler to ModelSerializer interface for DatabaseStore |
+| `Format` | Multi-format file I/O (YAML, YAMLS, JSON, JSONL, Marshal, XML) |
+| `Adapter` | Storage adapter registry and factory (Memory, FileSystem, SQLite) |
+
+### Format handlers (`lib/lutaml/store/format/`)
+
+All inherit from `Format::Base`. Six formats: `Yaml`, `Yamls`, `Json`, `Jsonl`, `MarshalFormat`, `Xml`. Each implements `serialize`/`deserialize`, optional `serialize_many`/`deserialize_many`, `extension`, `glob_pattern`, and `binary?`. Registered in `Format::FORMATS` hash and resolved via `Format.resolve(:symbol)`.
 
 ### Storage adapters (`lib/lutaml/store/adapter/`)
 
-All inherit from `Adapter::Base`. Three backends: `Memory`, `FileSystem`, `SQLite`. The `DatabaseStore` creates the adapter internally via `BasicStore`; the adapter type is passed as `adapter: :memory`, `adapter: { type: :filesystem, path: "..." }`, etc.
+All inherit from `Adapter::Base`. Three backends: `Memory`, `FileSystem`, `SQLite`. Registered in `Adapter` module and resolved via `Adapter.resolve(:type, options)`. New adapters can be added with `Adapter.register(:custom, CustomClass)` without modifying existing code (OCP).
 
-### HTTP caching
+### PackageStore and transports
 
-`HttpCache` provides HTTP-aware caching with ETags, conditional requests (304), Cache-Control, and Vary header support. Used by lutaml-hal to avoid re-fetching HAL resources.
+`PackageStore` provides structured multi-model persistence. `PackageDefinition` declares which models, assets, and metadata the package contains. Transports (`DirectoryTransport`, `ZipTransport`) handle reading/writing to disk. Format handlers determine serialization per model entry.
 
-### Serialization & integrity
+### FormatSerializer pattern
+
+`FormatSerializer` wraps a Format handler to implement the serializer interface (serialize/deserialize). This enables `DatabaseStore` to use any format (YAMLS, XML, Marshal, etc.) for key-value storage instead of the default hash serialization. Used for Glossarist-like YAMLS patterns.
+
+### HTTP caching
 
-`Compression` adds gzip support. `Integrity` provides SHA256 checksums for data verification (used by the FileSystem adapter).
+`HttpCache` provides HTTP-aware caching with ETags, conditional requests (304), Cache-Control, and Vary header support. Uses `to_json`/`from_json` for model-driven serialization.
 
 ## Conventions
 
 - Double-quoted strings (Rubocop enforced)
 - Specs use `expect` syntax (no `should`)
-- Documentation is in AsciiDoc (README.adoc, plan.adoc)
+- Documentation is in AsciiDoc (README.adoc)
+- All library code uses Ruby `autoload` (no `require_relative` or internal `require`)
 - Error hierarchy: `Lutaml::Store::Error` → `ConfigurationError`, `BackendError`, `ModelNotRegisteredError`, `InvalidKeyError`, `PolymorphicUpdateError`, `CompositeModelError`

data/README.adoc

@@ -309,40 +309,154 @@ store.destroy(model: User, user_id: "u1")
 == PackageStore
 
 `PackageStore` provides structured multi-model persistence with directory and ZIP
-transports. It is built on `PackageDefinition`, which declares the package schema
-declaratively.
+transports. Use it when you need to bundle multiple model types, binary assets,
+and metadata into a single loadable package.
+
+The workflow is: define the package schema with `PackageDefinition`, then load,
+query, modify, and save using `PackageStore`.
 
 === Define a package
 
+`PackageDefinition` declares the package structure — which models, assets, and
+metadata the package contains:
+
 [source,ruby]
 ----
-glossary = Lutaml::Store::PackageDefinition.new(name: "glossary") do |pkg|
+require "lutaml/model"
+require "lutaml/store"
+
+# Define your models
+class Concept < Lutaml::Model::Serializable
+  attribute :term, :string
+  attribute :definition, :string
+end
+
+class Author < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :email, :string
+end
+
+class GlossaryInfo < Lutaml::Model::Serializable
+  attribute :title, :string
+  attribute :version, :string
+end
+
+# Declare the package schema
+glossary = Lutaml::Store::PackageDefinition.new(
+  name: "glossary",
+  metadata_model: GlossaryInfo,
+  metadata_file: "glossary.yaml",
+  metadata_key: :title
+) do |pkg|
+  # Models stored in subdirectories, one file per instance
   pkg.model(model: Concept, key: :term, dir: "concepts", default_format: :yaml)
   pkg.model(model: Author, key: :name, dir: "authors", default_format: :json)
-  pkg.asset("glossary.yaml", type: :file)
-  pkg.metadata_model = GlossaryInfo
-  pkg.metadata_file = "glossary.yaml"
+
+  # Binary assets bundled in the package
+  pkg.asset("logo.png", type: :file)
+  pkg.asset("attachments", type: :directory)
 end
 ----
 
-=== Load and save packages
+Each `pkg.model` call registers a model type with:
+
+* `model:` — the `Lutaml::Model::Serializable` class
+* `key:` — attribute used as the unique identifier (becomes the filename)
+* `dir:` — subdirectory for this model type (use `file:` instead for a single-file model)
+* `layout:` — `:separate` (one file per instance, default) or `:grouped` (multiple instances per file)
+* `default_format:` — `:yaml`, `:json`, `:jsonl`, `:yamls`, or `:marshal`
+
+=== Directory structure
+
+When saved to disk, the glossary package produces:
+
+----
+my_glossary/
+├── glossary.yaml          # metadata (GlossaryInfo)
+├── concepts/              # Concept model instances
+│   ├── API.yaml
+│   ├── REST.yaml
+│   └── YAML.yaml
+├── authors/               # Author model instances
+│   ├── john_doe.json
+│   └── jane_smith.json
+├── logo.png               # asset file
+└── attachments/           # asset directory
+    └── spec.pdf
+----
+
+=== Load and query
 
 [source,ruby]
 ----
 # Load from directory
-store = Lutaml::Store::PackageStore.load(glossary, "./my_glossary", transport: :directory)
+store = Lutaml::Store::PackageStore.load(glossary, "./my_glossary")
 
-# Load from ZIP
+# Load from ZIP file
 store = Lutaml::Store::PackageStore.load(glossary, "./glossary.zip", transport: :zip)
 
+# Access metadata
+store.metadata  # => GlossaryInfo instance
+
 # Query models
-concepts = store.models_for(Concept)
-store.model_count(Concept)  # => 42
-store.fetch_model(Concept, "API")
+concepts = store.models_for(Concept)   # => array of Concept instances
+concept = store.fetch_model(Concept, "API")
+store.model_count(Concept)             # => 3
+store.model_exists?(Concept, "REST")   # => true
+
+# Access assets
+store.asset("logo.png")  # => binary content
+store.asset_paths        # => ["logo.png", "attachments/spec.pdf"]
+
+# Package statistics
+store.stats
+# => { package: "glossary", models: { "Concept" => 3, "Author" => 2 },
+#      assets: 2, metadata: true }
+----
+
+=== Modify and save
+
+[source,ruby]
+----
+# Add models
+store.add_model(Concept.new(term: "JSON", definition: "..."))
+store.add_models([concept1, concept2])
+
+# Remove models
+store.remove_model(Concept, "deprecated_term")
+
+# Add/remove assets
+store.add_asset("diagram.svg", svg_content)
+store.remove_asset("old_diagram.svg")
+
+# Save to directory (default format per model)
+store.save("./output")
+
+# Save to ZIP with per-model format overrides
+store.save("./glossary.zip", transport: :zip, formats: { Concept => :json })
+
+# Save with global format override
+store.save("./output", format: :yaml)
+
+# Bulk operations
+store.clear_models(Concept)  # remove all Concept instances
+store.clear_all              # remove everything
+----
+
+=== Per-model format override
+
+The `save` method accepts format overrides:
+
+[source,ruby]
+----
+# Global format for all models
+store.save("./out", format: :json)
+
+# Per-model format
+store.save("./out", formats: { Concept => :yaml, Author => :jsonl })
 
-# Modify and save
-store.add_model(Concept.new(term: "REST", definition: "..."))
-store.save("./output", transport: :zip)
+# Default: each model uses its default_format from the definition
+store.save("./out")
 ----
 
 === Package transports

data/lib/lutaml/store/adapter/base.rb

@@ -8,6 +8,8 @@ module Lutaml
           @config = config
         end
 
+        # ── Key-value operations ──
+
         def get(key)
           raise NotImplementedError
         end
@@ -60,6 +62,32 @@ module Lutaml
           keys.each_with_object({}) { |k, h| h[k] = delete(k) }
         end
 
+        # ── Query operations ──
+
+        # Execute a query specification.
+        # Returns array of [storage_key, hash_data] pairs, sorted and paginated.
+        # Returns nil to indicate "not supported — fall back to in-memory scan".
+        def execute_query(_query)
+          nil
+        end
+
+        # Count matching records without returning data.
+        # Returns nil to indicate "not supported — count execute_query results".
+        def count_query(_query)
+          nil
+        end
+
+        # Fetch a batch of [storage_key, hash_data] pairs for keyset pagination.
+        # Returns nil to indicate "not supported — fall back to in-memory".
+        def batch_query(_query, _after: nil, _limit: 1000)
+          nil
+        end
+
+        # Execute a block atomically. No-op for adapters without transaction support.
+        def transaction
+          yield
+        end
+
         def stats
           { adapter: self.class.name }
         end