singulus 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac98626fb3bc3db2c925dc5a31d25655501aa36544907ee9ba95d87b3e7e3917
-  data.tar.gz: 371565dd472005e3a4038a0fd7ad1d9fa2679fe237b610072101c5a541b7f821
+  metadata.gz: 2d1789b73a6f295eb931426f74275d5103ee163683754c29d8566c58f5054bea
+  data.tar.gz: af0fdfb83a78959d15d1d866c195926e3c99407ee5e90629ef2e04904ee83294
 SHA512:
-  metadata.gz: 5a6826300e20a88e8ae1e811cd1525c7f3cd38dcb6628d22608c92e2fc9ebc7029774288b2b990742783222f98f9054d188e5d892852a3bc7da8cf74181f71cc
-  data.tar.gz: 8d7b79fbcaac93d423b22c82856539e57c6ed3f718cbed8a22a1ca2f6760c45d2e47c42c1db3a11bfb1bda1033cf6800cfcf3029474693add6f54e8fb876855f
+  metadata.gz: fbe8c5420941bedf97c2bf995b3131afa7e2d5777a8c6a46c9851965012acf250a7372b79d8a6721b8a8a4f3dc5f9edd5c919d2654ae14098d14be749e8608ed
+  data.tar.gz: 6ae106c3ebbd2efc6cde98511b7ce47691b3c9949707b6f478e2dc2ffe0db98e429bcc644c735b587820bc77419b989d319e02ed88f808a14512d0c62c196c9c

data/.yardopts

@@ -0,0 +1,11 @@
+--markup markdown
+--main README.md
+--title "Singulus API Reference"
+--no-private
+--query '!object.path.start_with?("Singulus::Internal")'
+--fail-on-warning
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-09-08
+
+### Changed
+
+- Organized specs by configuration, Singleton, Multiton lifecycle, retention, and runtime security responsibilities.
+- Fixed the Multiton test helper to apply the requested mode without requiring a retention strategy.
+
+### Added
+
+- YARD reference for configuration, Singleton and Multiton APIs, with types, errors, lifecycle semantics, and examples.
+- Local documentation task and CI generation with warnings treated as failures.
+
 ### Fixed
 
 - Completed the final RuboCop cleanup across Multiton and specs.
@@ -73,5 +85,6 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 - Protect common reflective constructor access paths.
 - Protect captured `Method` and `UnboundMethod` paths in `:runtime` mode.
 
-[Unreleased]: https://github.com/Rubcraft/singulus/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/Rubcraft/singulus/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/Rubcraft/singulus/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Rubcraft/singulus/releases/tag/v0.1.0

data/README.md

@@ -241,6 +241,26 @@ bundle exec rake build
 
 SimpleCov enforces line and branch coverage, while CI tests supported Ruby versions independently from RuboCop.
 
+## API documentation
+
+Generate the YARD reference locally:
+
+```bash
+bundle install
+bundle exec rake yard
+```
+
+Open `doc/index.html` in a browser. The reference includes configuration,
+include-time options, errors, and the class methods installed by Singleton
+and Multiton. Installed methods appear on their pattern module's page; call
+these on your including class, while calling `.with` on the pattern module.
+The configuration object's reader/writer contract is documented under
+`Singulus.configuration`; its concrete class remains private.
+
+`.yardopts` excludes private implementation details. Generated HTML and the
+YARD cache are ignored by Git. Documentation generation fails on YARD warnings
+and runs in the CI quality job and `bundle exec rake ci`.
+
 ## Releasing
 
 Repository initialization, version-control operations, and release-tag creation are managed by the Rubcraft Toolkit. Singulus itself does not prescribe or duplicate those commands.

data/lib/singulus/internal/configuration.rb

@@ -2,15 +2,24 @@
 
 module Singulus
   module Internal
+    # Mutable defaults exposed through Singulus.configuration, not a public type.
+    # @private
     class Configuration
       MODES = %i[standard strict runtime].freeze
 
+      # Returns the mode applied to subsequently installed classes.
+      # @return [Symbol] :standard, :strict, or :runtime
       attr_reader :default_mode
 
+      # Initializes defaults in strict mode.
       def initialize
         self.default_mode = :strict
       end
 
+      # Sets the default for subsequently installed classes.
+      # @param mode [Symbol, String] standard, strict, or runtime
+      # @return [Symbol] normalized mode
+      # @raise [Singulus::Error] if the mode is unsupported
       def default_mode=(mode)
         mode = normalize_mode(mode)
 

data/lib/singulus/internal/errors.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
 module Singulus
+  # Public base exception for Singulus policy and configuration failures.
+  #
+  # Rescue this class for invalid modes/retention, locked registry settings,
+  # recursive Multiton initialization, and hardening violations. Specialized
+  # subclasses are private implementation details. Ruby and application errors
+  # (such as ArgumentError or initializer failures) are not wrapped.
+  #
+  # @example Handle a rejected configuration
+  #   begin
+  #     Singulus.configure { |config| config.default_mode = :unknown }
+  #   rescue Singulus::Error => error
+  #     warn error.message
+  #   end
   class Error < StandardError; end
 
   module Internal

data/lib/singulus/internal/singleton_class_methods.rb

@@ -3,6 +3,7 @@
 module Singulus
   module Internal
     module SingletonClassMethods
+      # See {Singulus::Singleton.instance} for the public contract.
       def instance
         return super unless Internal.locally_hardened?(self)
 
@@ -11,11 +12,13 @@ module Singulus
         instance
       end
 
+      # See {Singulus::Singleton.singulus} for the public contract.
       def singulus(mode:)
         Internal.set_mode!(self, mode)
         self
       end
 
+      # See {Singulus::Singleton.singulus_mode} for the public contract.
       def singulus_mode
         Internal.mode_for(self)
       end

data/lib/singulus/multiton.rb

@@ -1,10 +1,153 @@
 # frozen_string_literal: true
 
 module Singulus
+  # Provides a synchronized registry of instances indexed by normalized keys.
+  #
+  # Include this module and call `.instance_for` on the including class.
+  # Uniqueness lasts only while an entry is retained: deletion, expiration,
+  # eviction, or weak-reference collection allows a new object for the same key,
+  # even if application code still holds a previously released instance.
+  # Strict/runtime modes reject duplication and subclassing with {Error}.
+  # Standard-mode subclasses start with independent, default-configured registries.
+  #
+  # Methods documented below as class methods are installed on the including
+  # class, except {.with}, which is called on this module. Configure classes
+  # at boot before using them concurrently.
+  #
+  # @example Reuse a tenant-specific service
+  #   class TenantService
+  #     include Singulus::Multiton
+  #     def initialize(tenant_id)
+  #       @tenant_id = tenant_id
+  #     end
+  #   end
+  #   TenantService.instance_for(10).equal?(TenantService.instance_for(10)) # => true
   module Multiton
+    # @!method self.instance_for(identifier, *args, **kwargs, &block)
+    #   Returns the retained instance for a key, or constructs and stores one.
+    #
+    #   The normalizer determines the registry key, but the original identifier,
+    #   additional arguments, keywords, and block are forwarded to `initialize` only
+    #   on a cache miss. A hit ignores the additional initialization inputs.
+    #   Construction and registry access are synchronized per class. Expired and dead
+    #   weak entries are purged first; a hit refreshes LRU order, but never the TTL.
+    #   Initializer and key-normalizer exceptions propagate. Failed initialization
+    #   is not cached, so a later call may retry.
+    #
+    #   @param identifier [Object] original identifier passed first to initialize
+    #   @param args [Array<Object>] remaining positional initializer arguments
+    #   @param kwargs [Hash] initializer keyword arguments
+    #   @param block [Proc, nil] block forwarded to initialize on a miss
+    #   @return [Object] instance of the receiving class
+    #   @raise [Error] if initialization recursively requests the same normalized key
+    #   @see multiton_key
+    #   @see multiton_retention
+
+    # @!method self.instance?(identifier)
+    #   Checks whether a live entry exists without constructing an instance.
+    #
+    #   Purges expired/dead entries and does not refresh LRU order or TTL.
+    #   Key-normalizer exceptions propagate.
+    #
+    #   @param identifier [Object] identifier to normalize and look up
+    #   @return [Boolean] whether the normalized key is registered
+
+    # @!method self.delete_instance(identifier)
+    #   Removes registry ownership of a live entry and returns its instance.
+    #
+    #   Purges expired/dead entries first. Existing external references stay valid;
+    #   a later lookup can construct another instance. Normalizer exceptions propagate.
+    #
+    #   @param identifier [Object] identifier to normalize and remove
+    #   @return [Object, nil] removed instance, or nil if no live entry exists
+
+    # @!method self.clear_instances
+    #   Releases all registry entries after purging expired/dead entries.
+    #
+    #   External references remain valid. The empty registry allows changes to its
+    #   key normalizer and retention policy.
+    #
+    #   @return [Integer] number of live entries removed
+
+    # @!method self.instance_count
+    #   Counts registered entries after purging expired/dead entries.
+    #   @return [Integer] current registry size
+
+    # @!method self.instance_keys
+    #   Returns a frozen snapshot of keys after purging expired/dead entries.
+    #
+    #   Keys are normalized keys, not necessarily the original identifiers. Strings,
+    #   arrays, and hashes are recursively copied/frozen when registered; other key
+    #   objects are not copied. This operation does not refresh LRU order or TTL.
+    #
+    #   @return [Array<Object>] frozen array of currently registered keys
+
+    # @!method self.singulus(mode: nil, retention: nil, ttl: nil, max_size: nil)
+    #   Updates the class mode and/or retention policy, returning the class.
+    #
+    #   Mode is applied first; a subsequent retention error does not roll it back.
+    #   TTL/capacity settings are ignored unless retention is provided.
+    #
+    #   @param mode [Symbol, String, nil] hardening mode; nil leaves it unchanged
+    #   @param retention [Symbol, String, nil] strategy; nil leaves it unchanged
+    #   @param ttl [Numeric, nil] positive lifetime in seconds for ttl/bounded
+    #   @param max_size [Integer, nil] positive capacity for lru/bounded
+    #   @return [Class] receiving class
+    #   @raise [Error] for invalid settings or retention changes on a nonempty registry
+    #   @see multiton_retention
+
+    # @!method self.singulus_mode
+    #   Returns this class's current hardening mode.
+    #   @return [Symbol] :standard, :strict, or :runtime
+
+    # @!method self.multiton_key(&block)
+    #   Reads or replaces the key normalizer used by identifier-based operations.
+    #
+    #   The block receives the original identifier. Its result becomes the registry
+    #   key, with strings, arrays, and hashes recursively copied/frozen. Other objects
+    #   must keep stable `hash` and `eql?` behavior while registered. No block means
+    #   read the current normalizer; nil means identifiers are used directly.
+    #   Clear the registry before changing normalization. Block exceptions propagate
+    #   from subsequent identifier-based operations.
+    #
+    #   @param block [Proc, nil] normalizer to install, or nil to read
+    #   @yield [identifier] computes a registry key
+    #   @yieldparam identifier [Object] original identifier
+    #   @yieldreturn [Object] stable key
+    #   @return [Class, Proc, nil] class when setting; current normalizer when reading
+    #   @raise [Error] if setting a normalizer while live entries remain
+    #   @example Normalize case before creating instances
+    #     TenantService.multiton_key { |id| id.to_s.downcase }
+
+    # @!method self.multiton_retention(strategy = nil, ttl: nil, max_size: nil)
+    #   Reads or replaces the registry retention policy (initially `:forever`).
+    #
+    #   `forever` holds entries until explicit release; `weak` holds weak references.
+    #   Neither accepts TTL or capacity. `lru` requires only max_size and evicts the
+    #   least recently accessed entry. `ttl` requires only ttl and expires entries
+    #   from their creation time using the monotonic clock. `bounded` requires both.
+    #   Expiration is lazy, checked during registry operations, not by a background
+    #   worker. TTL never slides on access. All policies can allow new instances
+    #   after an entry is released. Settings may change only on an empty registry.
+    #
+    #   @param strategy [Symbol, String, nil] forever, weak, lru, ttl, or bounded;
+    #     nil reads the current strategy and ignores other arguments
+    #   @param ttl [Numeric, nil] positive seconds (converted with to_f)
+    #   @param max_size [Integer, nil] positive capacity (converted with to_i)
+    #   @return [Class, Symbol] class when setting; strategy when reading
+    #   @raise [Error] for an unknown strategy, incompatible/missing/nonpositive
+    #     options, or a nonempty registry
+    #   @example Combine time and capacity bounds
+    #     TenantService.clear_instances
+    #     TenantService.multiton_retention(:bounded, ttl: 300, max_size: 100)
+
+    # Supported internal retention names.
+    # @private
     RETENTIONS = %i[forever lru ttl bounded weak].freeze
     private_constant :RETENTIONS
 
+    # Internal registry entry, optionally holding a weak reference.
+    # @private
     Entry = Struct.new(:value, :expires_at, keyword_init: true) do
       def instance
         value.is_a?(WeakRef) ? value.__getobj__ : value
@@ -19,10 +162,35 @@ module Singulus
     private_constant :Entry
 
     class << self
+      # Installs the pattern when Ruby evaluates `include`.
+      # @private
       def included(base)
         install(base)
       end
 
+      # Builds an independent module with mode and optional retention settings.
+      #
+      # Defaults are captured now; mode and retention validation happens on inclusion.
+      # `ttl` and `max_size` are applied only when `retention` is supplied.
+      # See {.multiton_retention} for supported combinations.
+      #
+      # @param mode [Symbol, String, nil] :standard, :strict, or :runtime;
+      #   nil uses the configured default
+      # @param options [Hash] mode and registry settings
+      # @option options [Symbol, String] :mode alternative to positional mode
+      # @option options [Symbol, String] :retention registry retention strategy
+      # @option options [Numeric] :ttl positive lifetime in seconds
+      # @option options [Integer] :max_size positive registry capacity
+      # @return [Module] configured module to include in a class
+      # @raise [ArgumentError] if both mode forms or unknown options are supplied
+      # @raise [Error] on inclusion for invalid mode or retention settings
+      # @example Limit registry capacity
+      #   class TenantService
+      #     include Singulus::Multiton.with(:strict, retention: :lru, max_size: 100)
+      #     def initialize(tenant_id)
+      #       @tenant_id = tenant_id
+      #     end
+      #   end
       def with(mode = nil, **options)
         resolved_mode = options.delete(:mode)
 
@@ -43,6 +211,8 @@ module Singulus
         end
       end
 
+      # Installs guards and a fresh registry on a class.
+      # @private
       def install(base, mode: Singulus.configuration.default_mode)
         Internal.initialize_managed_class!(base, kind: :multiton, mode: mode)
 
@@ -71,7 +241,10 @@ module Singulus
       end
     end
 
+    # Implementation of methods installed on each Multiton class.
+    # @private
     module ClassMethods
+      # See {Singulus::Multiton.instance_for} for the public contract.
       def instance_for(identifier, ...)
         key = singulus_multiton_key_for(identifier)
 
@@ -102,6 +275,7 @@ module Singulus
         end
       end
 
+      # See {Singulus::Multiton.instance?} for the public contract.
       def instance?(identifier)
         key = singulus_multiton_key_for(identifier)
 
@@ -111,6 +285,7 @@ module Singulus
         end
       end
 
+      # See {Singulus::Multiton.delete_instance} for the public contract.
       def delete_instance(identifier)
         key = singulus_multiton_key_for(identifier)
 
@@ -120,6 +295,7 @@ module Singulus
         end
       end
 
+      # See {Singulus::Multiton.clear_instances} for the public contract.
       def clear_instances
         singulus_multiton_mutex.synchronize do
           singulus_multiton_purge_expired!
@@ -129,6 +305,7 @@ module Singulus
         end
       end
 
+      # See {Singulus::Multiton.instance_count} for the public contract.
       def instance_count
         singulus_multiton_mutex.synchronize do
           singulus_multiton_purge_expired!
@@ -136,6 +313,7 @@ module Singulus
         end
       end
 
+      # See {Singulus::Multiton.instance_keys} for the public contract.
       def instance_keys
         singulus_multiton_mutex.synchronize do
           singulus_multiton_purge_expired!
@@ -143,16 +321,19 @@ module Singulus
         end
       end
 
+      # See {Singulus::Multiton.singulus} for the public contract.
       def singulus(mode: nil, retention: nil, ttl: nil, max_size: nil)
         Internal.set_mode!(self, mode) if mode
         multiton_retention(retention, ttl: ttl, max_size: max_size) if retention
         self
       end
 
+      # See {Singulus::Multiton.singulus_mode} for the public contract.
       def singulus_mode
         Internal.mode_for(self)
       end
 
+      # See {Singulus::Multiton.multiton_key} for the public contract.
       def multiton_key(&block)
         return @__singulus_multiton_key_normalizer__ unless block
 
@@ -161,6 +342,7 @@ module Singulus
         self
       end
 
+      # See {Singulus::Multiton.multiton_retention} for the public contract.
       def multiton_retention(strategy = nil, ttl: nil, max_size: nil)
         return @__singulus_multiton_retention__ unless strategy
 

data/lib/singulus/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Singulus
-  VERSION = "0.1.0"
+  # Current gem version in semantic versioning format.
+  # @return [String] version used by the gem specification
+  VERSION = "0.1.1"
 end

data/lib/singulus.rb

@@ -15,7 +15,19 @@ require_relative "singulus/internal/singleton_class_methods"
 require_relative "singulus/internal/runtime_hardening"
 require_relative "singulus/multiton"
 
+# Configurable Singleton and keyed Multiton patterns for a Ruby process.
+#
+# Require `singulus`, then include {Singleton} or {Multiton} in a class.
+# The default mode is `:strict`; `:standard` relaxes local guards and
+# `:runtime` adds process-wide Method/UnboundMethod guards for managed classes.
+# Runtime hardening is not a sandbox for code running in the same process.
+#
+# @see Singleton
+# @see Multiton
+# @see Error
 module Singulus
+  # Implementation details; not a supported public namespace.
+  # @private
   module Internal
     CONSTRUCTORS = %i[new allocate].freeze
 
@@ -137,10 +149,37 @@ module Singulus
   private_constant :Internal
 
   class << self
+    # Returns the mutable process-wide defaults for subsequently installed classes.
+    #
+    # Use the returned object's `default_mode` reader and `default_mode=` writer;
+    # its concrete class is private. The reader returns a Symbol. The writer accepts
+    # `:standard`, `:strict`, `:runtime`, or their String forms, and raises
+    # {Error} for invalid modes. Existing managed classes keep their mode.
+    # Setting the writer directly does not install runtime guards until a runtime
+    # class is installed; use {configure} to enable them immediately.
+    #
+    # @return [#default_mode, #default_mode=] shared configuration object
+    # @example Read the default
+    #   Singulus.configuration.default_mode # => :strict
     def configuration
       @configuration ||= Internal::Configuration.new
     end
 
+    # Yields the shared configuration and enables runtime guards when requested.
+    #
+    # Configure during application boot, before defining managed classes or
+    # capturing constructor references. Runtime patches are installed once and
+    # remain installed for the life of the process. Exceptions from the block
+    # propagate; changes already made to the configuration are not rolled back.
+    #
+    # @yield [config] changes defaults for future class installations
+    # @yieldparam config [#default_mode, #default_mode=] mutable configuration
+    # @yieldreturn [Object] ignored
+    # @return [#default_mode, #default_mode=] shared configuration after the block
+    # @raise [ArgumentError] if no block is given
+    # @raise [Error] if the block assigns an unsupported default mode
+    # @example Enable runtime hardening during boot
+    #   Singulus.configure { |config| config.default_mode = :runtime }
     def configure
       raise ArgumentError, "a block is required" unless block_given?
 
@@ -149,17 +188,82 @@ module Singulus
       configuration
     end
 
+    # Replaces the shared configuration with a new object in `:strict` mode.
+    #
+    # Does not change existing classes, clear instances, or uninstall runtime
+    # patches. Previously returned configuration objects are no longer shared.
+    #
+    # @return [#default_mode, #default_mode=] new configuration object
     def reset_configuration!
       @configuration = Internal::Configuration.new
     end
   end
 
+  # Provides one lazily initialized, thread-safe instance per class and process.
+  #
+  # Include this module and call `.instance` on the including class. Construction
+  # uses a zero-argument initializer. In strict/runtime modes constructors are
+  # sealed after the first successful access, and duplication and inheritance
+  # raise {Error}. Standard mode delegates singleton semantics to Ruby Singleton,
+  # which rejects instance duplication with TypeError.
+  #
+  # Methods documented below as class methods are installed on the including
+  # class, except {.with}, which is called on this module.
+  #
+  # @example Share one service
+  #   class Settings
+  #     include Singulus::Singleton
+  #   end
+  #   Settings.instance.equal?(Settings.instance) # => true
   module Singleton
+    # @!method self.instance
+    #   Returns the class's shared instance, constructing it once if needed.
+    #
+    #   Initialization is synchronized by Ruby Singleton. Initializer exceptions
+    #   propagate and construction can be retried. Strict/runtime modes seal
+    #   constructors after successful access. Recursive `.instance` calls from the
+    #   initializer are unsupported by Ruby Singleton.
+    #
+    #   @return [Object] instance of the receiving class
+
+    # @!method self.singulus(mode:)
+    #   Changes this class's hardening mode.
+    #
+    #   Switching to runtime installs process-wide guards. Switching away does not
+    #   uninstall them. A sealed Singleton cannot downgrade to standard mode.
+    #
+    #   @param mode [Symbol, String] :standard, :strict, or :runtime
+    #   @return [Class] receiving class for chaining
+    #   @raise [Error] for an invalid mode or a downgrade after constructor sealing
+
+    # @!method self.singulus_mode
+    #   Returns this class's current hardening mode.
+    #   @return [Symbol] :standard, :strict, or :runtime
+
+    # Inclusion helpers for the public mixin.
     class << self
+      # Installs the pattern when Ruby evaluates `include`.
+      # @private
       def included(base)
         Internal.install_singleton!(base)
       end
 
+      # Builds an independent module with an include-time hardening mode.
+      #
+      # The default is captured when this method is called. Mode validation occurs
+      # when the returned module is included in a class.
+      #
+      # @param mode [Symbol, String, nil] :standard, :strict, or :runtime;
+      #   nil uses the configured default
+      # @param options [Hash] keyword form of the mode
+      # @option options [Symbol, String] :mode alternative to positional mode
+      # @return [Module] module to include in the managed class
+      # @raise [ArgumentError] if both mode forms or unknown options are supplied
+      # @raise [Error] on inclusion if the resolved mode is unsupported
+      # @example Select a mode for one class
+      #   class Settings
+      #     include Singulus::Singleton.with(mode: :runtime)
+      #   end
       def with(mode = nil, **options)
         resolved_mode = options.delete(:mode)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: singulus
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Juan Furattini
@@ -18,6 +18,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md