briefly 0.1.0

data/lib/briefly.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "candor"
+
+require "briefly/version"
+require "briefly/errors"
+require "briefly/definition"
+require "briefly/error_registry"
+require "briefly/facade"
+require "briefly/builder"
+
+# A terse, curated facade over an application's most frequently reached-for objects.
+#
+#   App = Briefly.define do
+#     use Briefly::Rails
+#     shortcut(:redis) { REDIS_POOL }
+#   end
+module Briefly
+  autoload :Rails, "briefly/rails"
+
+  @errors = ErrorRegistry.new
+
+  # The packs this gem ships, under the short names +use+ accepts. Values are constant paths, never
+  # constants: naming +Briefly::Rails::DB+ here would resolve it at load and defeat the autoload above.
+  @packs = {
+    "rails" => "Briefly::Rails",
+    "rails/config" => "Briefly::Rails::Config",
+    "rails/env" => "Briefly::Rails::Env",
+    "rails/view" => "Briefly::Rails::View",
+    "rails/db" => "Briefly::Rails::DB",
+    "rails/reload" => "Briefly::Rails::Reload"
+  }
+
+  class << self
+    # Builds a facade. The block is +instance_eval+'d on a {Briefly::Builder}.
+    #
+    # @yield [] the shortcut declarations
+    # @return [Briefly::Facade]
+    def define(&) = Facade.new.configure(&)
+
+    # Registers a pack under a short name, so +use "myapp/redis"+ resolves it. Re-registering a name
+    # overrides it. There is no inflection and no path guessing: this table is the only source of truth.
+    #
+    # @param name [String, Symbol] the short name
+    # @param pack [#install, String] the pack, or a constant path resolved on first use
+    # @return [self]
+    def register(name, pack)
+      @packs[name.to_s] = pack
+      self
+    end
+
+    # Resolves a short name to a pack. A registered constant path is resolved here, not at registration,
+    # so a pack's file loads only when something uses it.
+    #
+    # The path is walked one segment at a time rather than handed to +Object.const_get+ whole, so a
+    # +NameError+ raised *inside* a pack's file as it autoloads propagates untouched. Rescuing around
+    # the whole resolution would launder that bug into an {Briefly::UnknownPackError}.
+    #
+    # @param name [String, Symbol]
+    # @return [#install]
+    # @raise [Briefly::UnknownPackError] if +name+ is not registered, or names a path that does not resolve
+    def pack(name)
+      entry = @packs.fetch(name.to_s) { raise UnknownPackError, "unknown pack: #{name.inspect}" }
+      return entry unless entry.is_a?(String)
+
+      entry.split("::").reduce(Object) do |mod, segment|
+        unless mod.const_defined?(segment, false)
+          raise UnknownPackError, "pack #{name.inspect} names #{entry.inspect}, which does not resolve"
+        end
+
+        mod.const_get(segment, false)
+      end
+    end
+
+    # Registers a handler that applies to every shortcut on every facade, consulted only after the
+    # facade's own handlers. Takes no shortcut names.
+    #
+    # @param error_class [Class] matched against the raised error and its subclasses
+    # @yield [error, shortcut_name] the recovery block; its return value becomes the shortcut's value
+    # @return [self]
+    def rescue_from(error_class, &handler)
+      unless error_class.is_a?(Class)
+        raise ArgumentError, "rescue_from expects the error class first, got #{error_class.inspect}"
+      end
+      raise ArgumentError, "rescue_from(#{error_class}) requires a block" unless handler
+
+      @errors.add(error_class, nil, handler)
+      self
+    end
+
+    # @return [Briefly::ErrorRegistry] the global registry
+    attr_reader :errors
+  end
+end

data/sig/briefly/builder.rbs

@@ -0,0 +1,28 @@
+module Briefly
+  # Receives the DSL. Blocks are `instance_eval`'d here, never on the facade.
+  class Builder
+    @facade: Facade
+    @defs: Hash[Symbol, Definition]
+    @children: Hash[Symbol, Facade]
+    @errors: Array[Briefly::error_entry]
+
+    # One collected namespace pass per name, held until `compile!` has validated the whole tree.
+    @pending: Hash[Symbol, Builder]
+
+    attr_reader facade: Facade
+
+    def initialize: (Facade facade, Hash[Symbol, Definition] defs, Hash[Symbol, Facade] children) -> void
+    def use: (pack_ref pack, **untyped opts) -> self
+    def namespace: (Symbol name) { (?) [self: Builder] -> void } -> Symbol
+    def shortcut: (Symbol canonical, *Symbol aliases) { (?) [self: Facade] -> untyped } -> Symbol
+    def memoize: (Symbol name, **untyped opts) -> Symbol
+    def rescue_from: (Class error_class, *(Symbol | Array[Symbol]) names) { (StandardError, Symbol) -> untyped } -> self
+    def compile!: () -> Briefly::plan
+
+    private
+
+    def validate_name!: (untyped name) -> void
+    def purge: (Array[Symbol] names, except: Symbol) -> void
+    def fetch: (Symbol name) -> Definition
+  end
+end

data/sig/briefly/definition.rbs

@@ -0,0 +1,20 @@
+module Briefly
+  # One shortcut declaration: its canonical name, its aliases, its body, and whether it memoizes.
+  class Definition
+    attr_reader canonical: Symbol
+    attr_reader aliases: Array[Symbol]
+    attr_reader body: Proc
+    attr_reader raw_name: Symbol
+
+    # The `[file, line]` the compiled methods report; `Builder#namespace` overwrites it.
+    attr_accessor source_location: [ String, Integer ]
+
+    @memoized: bool
+
+    def initialize: (Symbol canonical, Array[Symbol] aliases, Proc body, [ String, Integer ] source_location) -> void
+    def initialize_copy: (Definition other) -> void
+    def memoize!: () -> void
+    def memoized?: () -> bool
+    def names: () -> Array[Symbol]
+  end
+end

data/sig/briefly/error_registry.rbs

@@ -0,0 +1,22 @@
+module Briefly
+  # An ordered list of `rescue_from` registrations, queried at dispatch time.
+  class ErrorRegistry
+    # A single registration. `names` is nil for facade-wide/global handlers.
+    class Entry < ::Struct[untyped]
+      attr_accessor klass: Class
+      attr_accessor names: Array[Symbol]?
+      attr_accessor handler: Briefly::handler
+
+      def self.new: (Class klass, Array[Symbol]? names, Briefly::handler handler) -> Entry
+    end
+
+    @entries: Array[Entry]
+    @mutex: Thread::Mutex
+
+    def initialize: () -> void
+    def add: (Class klass, Array[Symbol]? names, Briefly::handler handler) -> self
+    def scoped: (Symbol name) -> Array[Entry]
+    def wide: () -> Array[Entry]
+    def clear: () -> self
+  end
+end

data/sig/briefly/facade.rbs

@@ -0,0 +1,36 @@
+module Briefly
+  # The object returned by `Briefly.define`. Shortcuts are compiled onto its singleton class as real
+  # methods; RBS cannot see them, so they do not appear here.
+  class Facade
+    # Names a shortcut may not take.
+    RESERVED: Array[Symbol]
+
+    @__defs: Hash[Symbol, Definition]
+    @__aliases: Hash[Symbol, Symbol]
+    @__memos: Hash[Symbol, untyped]
+    @__monitor: Monitor
+    @__errors: ErrorRegistry
+    @__public: Array[Symbol]
+    @__children: Hash[Symbol, Facade]
+
+    def initialize: () -> void
+    def shortcuts: () -> Array[Symbol]
+    def shortcut?: (Symbol name) -> bool
+    def clear_memos!: () -> self
+    def reset!: () -> self
+    def configure: () ?{ (?) [self: Builder] -> void } -> self
+    def inspect: () -> String
+    def to_s: () -> String
+
+    private
+
+    def __prepare: () -> Builder
+    def __commit: (Briefly::plan plan) -> self
+    def __install: (Hash[Symbol, Definition] defs, Array[Briefly::error_entry] error_entries) -> self
+    def __remove_methods: (Array[Symbol] names) -> void
+    def __define: (Definition defn) -> void
+    def __call: (Symbol name, *untyped, **untyped) ?{ (?) -> untyped } -> untyped
+    def __memo: (Symbol name) { () -> untyped } -> untyped
+    def __handle: (StandardError error, Symbol name) -> untyped
+  end
+end

data/sig/briefly/rails.rbs

@@ -0,0 +1,30 @@
+module Briefly
+  # Shortcut pack for Rails applications. Loaded only when `Briefly::Rails` is referenced.
+  #
+  # An umbrella over `Config`, `Env`, `View` and `Reload`, plus `DB` under the `db` namespace. Each
+  # nested pack exposes `install` and nothing else.
+  module Rails
+    def self?.install: (Builder builder) -> Builder
+
+    # Configuration, paths and the application-wide singletons.
+    module Config
+      def self?.install: (Builder builder) -> Builder
+    end
+
+    # The environment and its predicates.
+    module Env
+      def self?.install: (Builder builder) -> Builder
+    end
+
+    # Helpers, routes and rendering outside a controller.
+    module View
+      def self?.install: (Builder builder) -> Builder
+    end
+
+    # One database, reached through one Active Record class. `base` is a constant path resolved on
+    # every call, so a reloaded class is never captured.
+    module DB
+      def self?.install: (Builder builder, ?base: String | Symbol | Module) -> Builder
+    end
+  end
+end

data/sig/briefly.rbs

@@ -0,0 +1,57 @@
+# A terse, curated facade over an application's most frequently reached-for objects.
+module Briefly
+  VERSION: String
+
+  # Distinguishes "not memoized yet" from a memoized `nil`.
+  UNSET: Object
+
+  # Base class for every error raised by Briefly.
+  class Error < StandardError
+  end
+
+  # Raised when `memoize` or `rescue_from` names a shortcut that does not exist.
+  class UnknownShortcutError < Error
+  end
+
+  # Raised when a shortcut name or alias would shadow a facade method.
+  class ReservedNameError < Error
+  end
+
+  # Raised when `use` names a pack that is not registered.
+  class UnknownPackError < Error
+  end
+
+  # A recovery block. Its return value becomes the shortcut's return value.
+  type handler = ^(StandardError error, Symbol shortcut_name) -> untyped
+
+  # A registered error handler, before `ErrorRegistry` receives it.
+  type error_entry = [ Class, Array[Symbol]?, handler ]
+
+  # A validated `configure` pass, ready to install: definitions, error handlers, namespace children,
+  # and one `[child, plan]` pair per namespace this pass collected. Recursive, so RBS types the tail
+  # as `untyped`.
+  type plan = [ Hash[Symbol, Definition], Array[error_entry], Hash[Symbol, Facade], Array[[ Facade, untyped ]] ]
+
+  # A pack is any object responding to `#install(builder)`. Options are optional: Ruby drops an empty
+  # `**` splat, so a pack that takes none needs no `**opts` parameter.
+  interface _Pack
+    def install: (Builder builder, **untyped opts) -> untyped
+  end
+
+  # A pack, or a name `Briefly.register`'d for one.
+  type pack_ref = _Pack | String | Symbol
+
+  # A registry entry: a pack, or a constant path resolved on first use.
+  type pack_entry = _Pack | String
+
+  self.@errors: ErrorRegistry
+  self.@packs: Hash[String, pack_entry]
+
+  # Shortcuts are compiled at runtime, so RBS cannot see them. Declare the ones you rely on in
+  # your own `sig/`, e.g. `App: Briefly::Facade` plus `def App.config: () -> untyped`.
+  def self.define: () ?{ (?) [self: Builder] -> void } -> Facade
+  def self.register: (String | Symbol name, pack_entry pack) -> Module
+  def self.pack: (String | Symbol name) -> _Pack
+  def self.rescue_from: (Class error_class) { (StandardError, Symbol) -> untyped } -> Module
+  def self.errors: () -> ErrorRegistry
+end

data/sig/manifest.yaml

@@ -0,0 +1,4 @@
+# Standard-library signatures these RBS files reference. Consumers' RBS/Steep load these
+# automatically when they depend on briefly. (The gem has no runtime gem dependencies.)
+dependencies:
+  - name: monitor # Facade's reentrant memo lock

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: briefly
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leonid Svyatov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: candor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+description: Declare one facade object per application area and reach your framework,
+  config and clients through short, real, introspectable methods. One runtime dependency
+  (candor), correct under Puma and Rails code reloading, with a batteries-included
+  Rails pack.
+email:
+- leonid@svyatov.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- briefly.gemspec
+- lib/briefly.rb
+- lib/briefly/builder.rb
+- lib/briefly/definition.rb
+- lib/briefly/error_registry.rb
+- lib/briefly/errors.rb
+- lib/briefly/facade.rb
+- lib/briefly/rails.rb
+- lib/briefly/rails/db.rb
+- lib/briefly/rails/reload.rb
+- lib/briefly/version.rb
+- sig/briefly.rbs
+- sig/briefly/builder.rbs
+- sig/briefly/definition.rbs
+- sig/briefly/error_registry.rbs
+- sig/briefly/facade.rbs
+- sig/briefly/rails.rbs
+- sig/manifest.yaml
+homepage: https://github.com/svyatov/briefly
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  documentation_uri: https://rubydoc.info/gems/briefly
+  source_code_uri: https://github.com/svyatov/briefly
+  changelog_uri: https://github.com/svyatov/briefly/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/svyatov/briefly/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.12
+specification_version: 4
+summary: A terse, curated facade over your application's most reached-for objects.
+test_files: []