keiyaku 0.1.0

data/lib/keiyaku/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Keiyaku
+  VERSION = "0.1.0"
+end

data/lib/keiyaku.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Loads the runtime, which is all an application needs: generated clients
+# require "keiyaku/runtime" directly. The generator is a separate file that
+# only the `keiyaku` executable pulls in, so nothing that merely calls an API
+# ever loads it.
+require_relative "keiyaku/runtime"

data/sig/keiyaku.rbs

@@ -0,0 +1,216 @@
+# Signatures for the runtime. Generated clients declare `class Client <
+# Keiyaku::Client` and `class Pet < Keiyaku::Model`, so without these their own
+# RBS would not resolve — which would defeat the point of emitting it.
+
+module Keiyaku
+  VERSION: String
+
+  # A parameter that was not passed, distinct from one passed as nil.
+  UNSET: untyped
+
+  # The words Ruby will not read as a name, which the generated method body
+  # needs too: a parameter may be called one of these.
+  KEYWORDS: Array[String]
+
+  class Error < StandardError
+  end
+
+  class CastError < Error
+  end
+
+  class Unsupported < Error
+  end
+
+  class HTTPError < Error
+    attr_reader status: Integer
+    attr_reader headers: Hash[String, String]
+    attr_reader body: String?
+
+    # The decoded body: a model if the operation documents a schema for this
+    # status, otherwise whatever JSON.parse returned.
+    attr_reader parsed: untyped
+
+    def initialize: (status: Integer, headers: Hash[String, String], body: String?, ?parsed: untyped) -> void
+  end
+
+  class ClientError < HTTPError
+  end
+
+  class ServerError < HTTPError
+  end
+
+  # The request did not happen. Every adapter raises this rather than its own
+  # library's class, so moving a client onto another HTTP stack does not
+  # change what the code around it has to rescue.
+  class ConnectionError < Error
+  end
+
+  # What a transport failure looks like from the stdlib.
+  TRANSPORT_ERRORS: Array[Class]
+
+  # One number for both phases, or `{ open:, read: }` for two.
+  type timeout = Integer | Float | Hash[Symbol, Integer | Float]
+
+  def self.timeouts: (timeout) -> [Integer | Float, Integer | Float]
+
+  def self.camelize: (String | Symbol) -> String
+  def self.snake: (String | Symbol) -> String
+
+  # Types are values, not a type language: Integer, [Pet], { String => Pet },
+  # :bool, :any. There is nothing more precise to say about them here.
+  def self.coerce: (untyped type, untyped value, String path) -> untyped
+  def self.dump: (untyped) -> untyped
+
+  # Keyed by an exact code, by a range like "4XX", or by :default, narrowest
+  # first. The table is the operation's, so its values are whatever it holds.
+  def self.for_status: (Hash[untyped, untyped] table, Integer status) -> untyped
+
+  # Returns a Keiyaku::Model subclass built at runtime; the generator emits a
+  # proper class declaration for each one alongside the code. The fields are a
+  # positional Hash so that a property named `from` cannot displace the option.
+  def self.model: (
+    Hash[Symbol, untyped] fields, ?required: Array[Symbol], ?from: Hash[Symbol, String], ?open: untyped
+  ) -> untyped
+
+  # The value type a schema becomes. Each generated model declares its own
+  # fields, `new` and `with`; what is here is what they all share.
+  class Model
+    def self.members: () -> Array[Symbol]
+    def self.types: () -> Hash[Symbol, untyped]
+    def self.json_names: () -> Hash[Symbol, String]
+    def self.required: () -> Array[Symbol]
+
+    # What `additionalProperties` said: false, true, or the type declared for
+    # the values of the properties the schema did not name.
+    def self.additional: () -> untyped
+    def self.open?: () -> bool
+
+    def self.cast: (untyped, ?String) -> untyped
+    def self.__define: (Hash[Symbol, untyped] fields, required: Array[Symbol], from: Hash[Symbol, String], open: untyped) -> void
+
+    def initialize: (**untyped) -> void
+
+    # A field by name, whether or not it is one Ruby will take through a dot,
+    # and on an open model the properties the document did not name.
+    def []: (String | Symbol) -> untyped
+
+    def with: (**untyped) -> self
+    def to_h: () -> Hash[Symbol, untyped]
+    def deconstruct: () -> Array[untyped]
+    def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+    def to_json_hash: () -> Hash[String, untyped]
+    def to_json: (*untyped) -> String
+  end
+
+  class OneOf
+    def self.[]: (*untyped variants, on: String, ?map: Hash[untyped, untyped]) -> OneOf
+    def initialize: (Array[untyped], String, Hash[untyped, untyped]) -> void
+    def cast: (untyped, ?String) -> untyped
+  end
+
+  # Keyed by the code itself or by the range the document wrote in place of
+  # one, which is a String because `2XX` is not a number.
+  class ByStatus
+    def self.[]: (Hash[Integer | String, untyped] types) -> ByStatus
+    def initialize: (Hash[Integer | String, untyped]) -> void
+    def []: (Integer status) -> untyped
+    def types: () -> Hash[Integer | String, untyped]
+
+    private
+
+    def normalise: (untyped status) -> untyped
+  end
+
+  class Upload
+    attr_reader io: untyped
+    attr_reader filename: String
+    attr_reader content_type: String
+
+    def initialize: (untyped io, ?filename: String?, ?content_type: String?) -> void
+    def read: () -> String
+  end
+
+  module Serialize
+    def self.query: (Hash[String, untyped], ?deep: Array[String]) -> Array[[String, String]]
+    def self.deep_object: (String name, untyped value) -> Array[[String, String]]
+    def self.path: (String name, untyped value, ?explode: bool) -> String
+    def self.simple: (String name, untyped value, ?explode: bool, ?escape: bool) -> String
+    def self.simple_part: (String name, untyped value, ?escape: bool) -> String
+    def self.stringify: (untyped) -> String
+    def self.multipart: (Hash[String, untyped], String boundary) -> String
+    def self.part: (String name, untyped value, String boundary) -> String
+  end
+
+  # Anything that can make a request. Pass one as `adapter:` to put the client
+  # on an HTTP stack the application already has. Response header names may be
+  # in any case; the client lower-cases them before reading any.
+  interface _Adapter
+    def call: (Symbol verb, untyped uri, Hash[String, String] headers, String? body) -> [Integer, Hash[String, untyped], String?]
+  end
+
+  # Autoloaded from `keiyaku/adapters/net_http` by the client that was given no
+  # adapter, so nothing has to require it to get the default.
+  class NetHTTPAdapter
+    include _Adapter
+
+    def initialize: (?timeout: timeout) -> void
+  end
+
+  # Loaded only by `require "keiyaku/adapters/faraday"`. Faraday's own types
+  # are deliberately not named here: the signature has to resolve whether or
+  # not the gem is installed.
+  class FaradayAdapter
+    include _Adapter
+
+    def initialize: (?untyped connection, ?timeout: timeout?, **untyped) -> void
+  end
+
+  # Loaded only by `require "keiyaku/adapters/http"`. Wraps the http.rb gem.
+  class HTTPAdapter
+    include _Adapter
+
+    def initialize: (?untyped client, ?timeout: timeout) -> void
+  end
+
+  class Client
+    def self.operations: () -> Hash[Symbol, Hash[Symbol, untyped]]
+    def self.server: (?String?) -> String?
+
+    # The schemes the document declares, by its own name for each, and the
+    # requirement that holds where an operation states none of its own.
+    def self.security: (?Hash[Symbol | String, untyped] schemes, ?default: untyped) -> untyped
+    def self.default_security: () -> Array[Array[Symbol]]
+
+    # A requirement is a list of alternatives, any one of which is enough,
+    # each naming the schemes that all have to be satisfied.
+    def self.requirement: (untyped) -> Array[Array[Symbol]]
+
+    def self.get: (Symbol name, String template, **untyped) -> void
+    def self.post: (Symbol name, String template, **untyped) -> void
+    def self.put: (Symbol name, String template, **untyped) -> void
+    def self.patch: (Symbol name, String template, **untyped) -> void
+    def self.delete: (Symbol name, String template, **untyped) -> void
+    def self.head: (Symbol name, String template, **untyped) -> void
+    def self.options: (Symbol name, String template, **untyped) -> void
+
+    def self.operation: (
+      Symbol verb, Symbol name, String template,
+      ?query: Array[Symbol], ?deep_object: Array[String], ?header: Hash[String, Symbol],
+      ?explode: Array[String], ?required: Array[Symbol | String],
+      ?body: untyped, ?form: untyped, ?multipart: untyped, ?content_type: String?, ?body_required: bool,
+      ?into: untyped, ?errors: Hash[untyped, untyped], ?security: untyped
+    ) -> void
+
+    def self.unsupported: (Symbol name, String reason) -> void
+
+    attr_reader base_url: String
+
+    # `auth:` is credentials by scheme name — a bare value only where the
+    # document declares one scheme, since with two there is nothing to say
+    # which it is.
+    def initialize: (
+      ?base_url: String?, ?auth: Hash[Symbol | String, untyped] | String | Array[String] | nil,
+      ?adapter: _Adapter?, ?timeout: timeout, ?retries: Integer, ?logger: untyped
+    ) -> void
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: keiyaku
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- merely
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Generates Ruby clients from OpenAPI documents that carry only what is
+  specific to one API — an operation table and the schema fields. Transport,
+  parameter serialization, casting and error mapping live in a shared
+  runtime, so a nineteen-operation client is about seventy lines. A schema
+  becomes a frozen value type with RBS emitted beside it, so terse Ruby
+  costs nothing in tooling. Constructs it cannot translate faithfully are
+  refused at generation time rather than emitted as plausible guesses.
+email:
+- git@merely.ca
+executables:
+- keiyaku
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- DESIGN.md
+- LICENSE.txt
+- README.md
+- exe/keiyaku
+- lib/keiyaku.rb
+- lib/keiyaku/adapters/faraday.rb
+- lib/keiyaku/adapters/http.rb
+- lib/keiyaku/adapters/net_http.rb
+- lib/keiyaku/emitter.rb
+- lib/keiyaku/emitter/rbs.rb
+- lib/keiyaku/emitter/security.rb
+- lib/keiyaku/names.rb
+- lib/keiyaku/runtime.rb
+- lib/keiyaku/version.rb
+- sig/keiyaku.rbs
+homepage: https://github.com/onyxblade/keiyaku
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/onyxblade/keiyaku
+  changelog_uri: https://github.com/onyxblade/keiyaku/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: OpenAPI clients as a table of operations, not a generated codebase.
+test_files: []