sortsmith 0.2.0 → 1.0.0

data/lib/sortsmith/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module Sortsmith
-  VERSION = "0.2.0"
+  #
+  # The current version of the Sortsmith gem
+  #
+  VERSION = "1.0.0"
 end

data/lib/sortsmith.rb

@@ -1,9 +1,56 @@
 # frozen_string_literal: true
 
-require_relative "sortsmith/sorter"
-require_relative "sortsmith/step"
 require_relative "sortsmith/version"
+require_relative "sortsmith/core_ext/enumerable"
+require_relative "sortsmith/sorter"
 
+##
+# Sortsmith provides a flexible, chainable API for sorting Ruby collections.
+#
+# The gem extends Ruby's built-in {Enumerable} module to provide an intuitive
+# sorting interface that reads like natural language and supports complex
+# sorting operations through method chaining.
+#
+# @example Basic usage
+#   users = ["Charlie", "alice", "Bob"]
+#   users.sort_by.downcase.sort
+#   # => ["alice", "Bob", "Charlie"]
+#
+# @example Hash sorting
+#   users = [
+#     { name: "Charlie", age: 25 },
+#     { name: "alice", age: 30 },
+#     { name: "Bob", age: 20 }
+#   ]
+#   users.sort_by.dig(:name).insensitive.sort
+#   # => sorted by name, case-insensitive
+#
+# @example Complex chaining
+#   users.sort_by.dig(:name, indifferent: true).downcase.desc.sort
+#   # => Extract name (works with both string/symbol keys), downcase, descending
+#
+# @see Sortsmith::Sorter The main sorting interface
+# @see Enumerable#sort_by The extended sort_by method
+#
+# @author Bryan "itsthedevman"
+# @since 0.1.0
+#
 module Sortsmith
+  ##
+  # Base error class for all Sortsmith-related exceptions.
+  #
+  # This provides a namespace for any custom errors that may be raised
+  # during sorting operations, making it easier to rescue Sortsmith-specific
+  # issues without catching unrelated StandardError instances.
+  #
+  # @example Rescuing Sortsmith errors
+  #   begin
+  #     complex_sort_operation
+  #   rescue Sortsmith::Error => e
+  #     handle_sorting_error(e)
+  #   end
+  #
+  # @since 0.1.0
+  #
   class Error < StandardError; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sortsmith
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-17 00:00:00.000000000 Z
+date: 2025-08-03 00:00:00.000000000 Z
 dependencies: []
 description: Sortsmith provides a flexible, chainable API for sorting Ruby collections.
   It supports sorting by object keys, methods, case sensitivity, and custom transformations.
@@ -25,17 +25,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- Steepfile
 - flake.lock
 - flake.nix
 - lib/sortsmith.rb
+- lib/sortsmith/core_ext/enumerable.rb
 - lib/sortsmith/sorter.rb
-- lib/sortsmith/step.rb
 - lib/sortsmith/version.rb
-- sig/sortsmith.rbs
-- sig/sortsmith/sorter.rbs
-- sig/sortsmith/step.rbs
-- sig/sortsmith/version.rbs
 homepage: https://github.com/itsthedevman/sortsmith
 licenses:
 - MIT
@@ -53,7 +48,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/Steepfile

@@ -1,8 +0,0 @@
-# D = Steep::Diagnostic
-
-target :lib do
-  signature "sig"
-  ignore_signature "sig/test"
-
-  check "lib"
-end

data/lib/sortsmith/step.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Sortsmith
-  #
-  # Represents a step in the sorting process
-  #
-  class Step < Data.define(:type, :block)
-    TYPES = [
-      TRANSFORMATION = :transformation,
-      FILTER = :filter
-    ].freeze
-
-    def perform(item)
-      block.call(item)
-    end
-  end
-end

data/sig/sortsmith/sorter.rbs

@@ -1,107 +0,0 @@
-module Sortsmith
-    interface _Sortable
-    def to_s: () -> String
-    def <=>: (self) -> Integer
-  end
-
-  class Sorter[Elem < _Sortable]
-    @enumerable: Enumerable[Elem]
-
-    @pipeline: Array[Step]
-
-    @direction: Symbol
-
-    #
-    # Creates a Sorter builder instance
-    #
-    # @param enumerable [Enumerable] The enumerable (Array, Hash) to sort
-    #
-    def initialize: (Enumerable[Elem] enumerable) -> void
-
-    #
-    # Finalizes the Sorter instance and sorts the enumerable
-    #
-    # @return [Enumerable] The sorted enumerable
-    #
-    def sort: () -> Enumerable[Elem]
-
-    #
-    # Adds a "filter" step to the sort pipeline.
-    # Filter steps are used to get data from the current item being sorted
-    # These are performed before transformation steps
-    #
-    # @param & [Proc] The block to execute
-    #
-    # @return [Self] The sorter instance
-    #
-    def add_filter: () { (untyped) -> untyped } -> self
-
-    #
-    # Adds a "transformation" step to the sort pipeline
-    # Transformation steps are used to transform data.
-    # These are performed after filter steps
-    #
-    # @param & [Proc] The block to execute
-    #
-    # @return [Self] The sorter instance
-    #
-    def add_transformation: () { (untyped) -> untyped } -> self
-
-    #
-    # Instructs the sorter to perform a fetch by key on the Hash being sorted
-    #
-    # @param key [String, Symbol, Any] The hash key to fetch
-    #
-    # @return [Self] The sorter instance
-    #
-    def by_key: ((String | Symbol | untyped) key) -> self
-
-    #
-    # Instructs the sorter to perform a method call on the object being sorted
-    #
-    # @param method [String, Symbol] The method name to call
-    #
-    # @return [Self] The sorter instance
-    #
-    def by_method: ((String | Symbol) method) -> self
-
-    alias by_attribute by_method
-
-    #
-    # Instructs the sorter to sort by a case insensitive value
-    #
-    # @return [Self] The sorter instance
-    #
-    def case_insensitive: () -> self
-
-    #
-    # Controls which direction the array will be sorted
-    #
-    # @return [Self] The sorter instance
-    #
-    def asc: () -> self
-
-    alias forward asc
-
-    #
-    # Controls which direction the array will be sorted
-    #
-    # @return [Self] The sorter instance
-    #
-    def desc: () -> self
-
-    alias reverse desc
-
-    private
-
-    def add_step: (type: Symbol) { (untyped) -> untyped } -> self
-
-    def select_filter_steps: () -> Array[Step]
-
-    def select_transformation_steps: () -> Array[Step]
-
-    def type_priority: (untyped value) -> Integer
-
-    def apply_transformations: (Array[Step] steps, untyped value) -> untyped
-  end
-end

data/sig/sortsmith/step.rbs

@@ -1,28 +0,0 @@
-module Sortsmith
-  #
-  # Represents a step in the sorting process
-  #
-  class Step < ::Data
-    TYPES: ::Array[Symbol]
-
-    FILTER: Symbol
-
-    TRANSFORMATION: Symbol
-
-    attr_reader type: Symbol
-
-    attr_reader block: ^(untyped) -> untyped
-
-    def self.new: (Symbol type, untyped block) -> instance
-                | (type: Symbol, block: untyped) -> instance
-
-    def self.[]: (Symbol type, untyped block) -> instance
-              | (type: Symbol, block: untyped) -> instance
-
-    def self.members: () -> [ :type, :block ]
-
-    def members: () -> [ :type, :block ]
-
-    def perform: (untyped item) -> untyped
-  end
-end

data/sig/sortsmith/version.rbs

@@ -1,3 +0,0 @@
-module Sortsmith
-  VERSION: String
-end

data/sig/sortsmith.rbs

@@ -1,4 +0,0 @@
-module Sortsmith
-  class Error < StandardError
-  end
-end