lutaml-store 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4917f68f56456a19670424157dd5001d243b9bd6d97618f445d306a7998e2a9f
-  data.tar.gz: 7076d765cf18cc91bfa9cf252bb0117ea8870c915bf1e7421648d9490de7e6a5
+  metadata.gz: 34e9babf679b2654a563c89d68552afd0b2d98d5725656eb9baa2f1a878a80f4
+  data.tar.gz: 599409d62bfe96b0e57147f620aef55ea88abe40b5183bdfb02511d3a91ea281
 SHA512:
-  metadata.gz: 897f40bf4972373587528a80afcc44ab2b0c159f2bba63a97f39cb997eff97d3633d7e34cabeb0dac37e1b337781f0aef60b9ffaae2b3a3426d5624b35fb7950
-  data.tar.gz: 1b79b56672ace97f0b6e57715b1b56b7f4638b1d426db57b8f57c5ed21eb461a7fd2ff4181f57afaa094d85c9b7da37f9e3d4771c04afecfcef0c268e86ddcd7
+  metadata.gz: 77f4022441c6b6ab2f63b5106a2ca3bba16abab82bf75adbe8569ec73a0eb6cd824891920e5571e7a2f7b39c9d56ac5bd2824418f24aa8577abf893645941062
+  data.tar.gz: dbe7804392b8b32135c77f3766b6976a8111a357b40bfdad563906d59205a0305dfd3f467b371ba423859a6ebbb8a7fa8d8baef905875a6097478763ed2d6b43

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-06-05 09:38:49 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: 57
+# 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: 12
+  Max: 13
 
-# Offense count: 79
+# 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: 4
+# Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 12
+  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: 36
+# Offense count: 51
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Enabled: false

data/README.adoc

@@ -17,8 +17,64 @@ It offers a unified interface for storing and retrieving complex model
 hierarchies, batch file I/O with multiple serialization formats, HTTP-aware
 caching, and package-based persistence with ZIP and directory transports.
 
+It also provides **read-only Sources** for working with data repositories that
+live outside your process — GitHub Pages, any static host, a REST API, a local
+package directory, or a `.zip` distribution — through one facade that never
+guesses which layer answered.
+
+== Quick start: read a LutaML data repository
+
+The same read API whether the data lives in the cloud, a local package, or a
+downloaded `.zip` — backends are configured, never guessed:
+
+[source,ruby]
+----
+require "lutaml/store"
+
+# From a cloud API (api.relaton.org is the reference implementation)
+repo = Lutaml::Store::Repository.new(
+  source: Lutaml::Store::Source.for(:rest,
+    base_url: "https://api.relaton.org", collection: "ietf"),
+  cache: Lutaml::Store::Source.for(:directory, path: "~/.cache/relaton/ietf"),
+)
+
+# From a local GCR-style package — identical read API
+repo = Lutaml::Store::Repository.new(
+  source: Lutaml::Store::Source.for(:directory, path: "~/gcr/relaton/ietf"),
+)
+
+# From a downloaded .zip distribution — same API
+repo = Lutaml::Store::Repository.new(
+  source: Lutaml::Store::Source.for(:zip, path: "ietf.zip"),
+)
+
+# Read
+repo.read("RFC 7231")        # => bytes
+repo.exist?("RFC 7231")      # => true
+repo.keys                     # => ["RFC 7231", ...]
+repo.manifest                 # => Lutaml::Store::Manifest
+
+# Parse into your model — the model class is declared, never inferred
+repo.get("RFC 7231", MyModel)
+
+# Search by metadata fields
+repo.search(docid: "RFC 7231")
+
+# Pull the whole collection into a local GCR-style package
+repo.pull!(into: "~/gcr/relaton", collection: "ietf")
+
+# Offline mode: never touch the source, serve from the local package only
+offline = Lutaml::Store::Repository.new(source: repo.source, cache: repo.cache, mode: :offline)
+offline.read("RFC 7231")     # served from the cache, no network
+
+
+
 == Features
 
+* **Repository** — the uniform facade: one read API over any source (cloud, local, zip), explicit cache, online/offline modes
+* **Source** (read-only) — Directory, Zip, Https (ETag/304), Rest (the lutaml cloud store API); 404 = NotFoundError, transport = BackendError
+* **Manifest** — the enumeration SSOT: keys, sha256 digests, opaque shard metadata
+* **Mirror** — pull any source into a GCR-style package (incremental, digest-verified); pack to a distributable .zip
 * **DatabaseStore** — high-level CRUD with model registry, polymorphism, composites
 * **PackageStore** — structured multi-model packages with ZIP and directory transport
 * **BasicStore** — low-level key-value store with optional cache, events, monitoring

data/docs/astro.config.mjs

@@ -0,0 +1,12 @@
+import { defineConfig } from "astro/config";
+import vue from "@astrojs/vue";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  site: "https://lutaml.github.io",
+  base: "/lutaml-store",
+  integrations: [vue()],
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});