haveapi-typescript-client 0.31.2 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c7d66d8b71e72b4cb440001fba34829c9c390dbe1e9a9330a4737724061348e
-  data.tar.gz: 0c07960f84ef143335056b9f577c7579c76104a2c877e851650e0a25f3c84008
+  metadata.gz: f82e8d0c5f9a906a98f55b2969f7a00a9f69efaa7aea7586eccb19ca03022102
+  data.tar.gz: ad342219999ef8533db09fd6aba8ccd546102af69c907916226e91bd6dba4d61
 SHA512:
-  metadata.gz: cf15eb58ef3a367bbb3626b6ef49e2a210b2e57cd09d62aac61701f7d6deafab98d3ea08b21398cee68b0129317605797c4e837096146829ec8c524eb4f26b2d
-  data.tar.gz: cc4ac2c6e44ac306b56482144521f24c726e2533e1cc1963778c236c513fd0eb45263cfedd6bd9ab336181f9c7c482c487a2ccf7794ab613ef733e376c3de042
+  metadata.gz: 6656aa62ba57f2cae74bd8f64d9e9b528860384b43f8d03624b97c0024360d8f6e24facd256892ab6bd000788ecc17a2c15154c5d1b8f9ebcf0ad7153dff406f
+  data.tar.gz: 8fb7f096cc83859f4a4415ebf33d387247367f8f2c8b05e93d560f5c41f10c9470b6334cb7fb2dc72b7cd999691decd8bb2b134584cd9bd59896393cc2f6a557

data/README.md

@@ -38,6 +38,22 @@ using the prepared dependencies and runs without contacting the API.
 Applications need a TypeScript compiler and the `haveapi-client` JavaScript
 runtime. The supported runtime version is exactly `0.30.2`.
 
+Both generation and `generate --check` require **Prettier 3.9.10** and Node.
+The repository's default Nix shell supplies them. For an installed Ruby gem,
+prepare the formatter in your application's tooling before generating:
+
+```sh
+npm install --save-dev --save-exact prettier@3.9.10
+export PRETTIER="$PWD/node_modules/.bin/prettier"
+```
+
+`PRETTIER` is an executable path, not a shell command. Alternatively, put the
+exact version's `prettier` executable on PATH. The Ruby gem does not install npm
+dependencies. Generation checks the formatter version and never downloads or
+installs tools. Fetch, help, library loading and documentation rendering do not
+require Prettier. Running an already generated client needs neither Prettier nor
+the Ruby generator.
+
 ## Fetch, save and generate
 
 The example API at `https://example.test/api/v1.0/` has `Widget#Update` at
@@ -69,6 +85,11 @@ The explicit generation version must match the saved snapshot. `--check` reports
 missing or stale output without changing it. Keep handwritten files outside
 `src/generated`.
 
+Generation formats only its temporary emitted source tree, using the packaged
+`lib/haveapi/typescript_client/prettier.json` defaults. Application Prettier
+configuration, EditorConfig and ignore files do not change generated output.
+The pure emitter and documentation adapters remain formatter-free.
+
 For Basic capture, set `WIDGET_PASSWORD` in your environment, then run:
 
 ```sh
@@ -190,10 +211,20 @@ Commit the whole generated tree and manifest together. Regenerate with the
 recorded schema and HaveAPI revision, and keep that generator/client pair
 together when reverting versions.
 
+The format-1 manifest records the formatter name, exact version and configuration
+SHA-256 alongside hashes of the final formatted files. Existing format-1 trees
+without formatter provenance can be regenerated normally; `--check` reports
+them as stale without writing. Missing tools, version mismatches and formatting
+errors leave the destination unchanged. Identical regeneration preserves file
+timestamps.
+
 An interrupted write can leave mixed output. Restore the committed generated
 tree before regenerating. If the first generation was interrupted before an
 ownership manifest was written, preserve that partial directory and generate
 into a fresh empty `src/generated`. Do not edit the manifest to bypass a refusal.
+When rolling back, restore the matching generator revision, generated tree and
+manifest together. An older generator's `--check` need not accept source
+formatted by a newer generator.
 
 The Ruby server can render examples using this generated interface; see
 [generated documentation profiles](docs/documentation.md).

data/docs/documentation.md

@@ -69,10 +69,16 @@ input wire names map to generated input names. The DSL has no separate input
 metadata carrier, so actions requiring input metadata produce a limitation.
 Inputs preserve omission, null, false, zero and empty strings. Unsafe integer IDs,
 invalid JSON and structured Custom query values cannot be rendered. Output keys
-remain wire names, with guards for optional, null and unknown values.
-
-Successful examples retain `data`, `meta`, `envelope` and `httpStatus`. Rejection
-examples inspect the runtime's error receipt without printing server diagnostics.
+remain wire names. Simple examples print the supplied output fields directly;
+thorough examples guard optional, null and unknown values before using them.
+
+Simple action examples assume that initialization and authentication have
+established `api`. They use `await` in an async context and show the exact call
+and sample output. Rejection examples import the runtime's `AsyncError` class.
+**With error handling** includes setup, error handling and the response receipt's
+`data`, `meta`, `envelope` and `httpStatus`. Both levels use the same validation
+and limitations. Rejection examples inspect the runtime's error receipt without
+printing server diagnostics.
 Requests are not retried. A successful request does not establish completion of
 a server-side operation; raw receipts cannot be passed to `waitForCompletion`.
 
@@ -81,8 +87,9 @@ a server-side operation; raw receipts cannot be passed to `waitForCompletion`.
 The generator provides `HaveAPI::TypeScriptClient::Documentation` through
 `require 'haveapi/typescript_client/documentation'`. Its factories accept a full
 description or saved snapshot. `resolve` returns a frozen canonical action;
-`render` returns the server's code or limitation result. Rendering performs no
-file, network, generator or compiler work.
+`render` returns the server's code or limitation result. Its context must expose
+`detail` as `:simple` or `:thorough`. Rendering performs no file, network,
+generator or compiler work.
 
 Rendering selects the current action, authentication provider and metadata
 namespace before recursively normalizing their contents. It leaves unrelated
@@ -90,8 +97,9 @@ description descendants untouched and keeps authorization decisions local to
 each render. Deterministic work checks grow unrelated subtrees while keeping
 the selected inputs and rendered source fixed.
 
-Focused unit checks compile the actual rendered programs against generated
-fixture modules with TypeScript 6, NodeNext/ES2022, `exactOptionalPropertyTypes`,
+The compilation checks compose simple action fragments with separately rendered
+setup and compile both detail levels against generated fixture modules with
+TypeScript 6, NodeNext/ES2022, `exactOptionalPropertyTypes`,
 `noUncheckedIndexedAccess` and `verbatimModuleSyntax`. They cover aliases, nested
 paths, filtered fields, stale contracts, supported authentication and errors.
 

data/haveapi-typescript-client.gemspec

@@ -14,5 +14,5 @@ Gem::Specification.new do |spec|
   spec.bindir = 'bin'
   spec.executables = ['haveapi-typescript-client']
   spec.require_paths = ['lib']
-  spec.add_dependency 'haveapi-client', '~> 0.31.2'
+  spec.add_dependency 'haveapi-client', '~> 0.32.0'
 end

data/lib/haveapi/typescript_client/documentation.rb

@@ -2,7 +2,7 @@ require_relative '../typescript_client'
 require 'uri'
 
 module HaveAPI::TypeScriptClient
-  # Names belong to the complete SDK; request-local help only limits their use.
+  # Names belong to the complete API client; request-local help only limits their use.
   class Documentation
     class Unsupported < StandardError; end
 
@@ -49,14 +49,20 @@ module HaveAPI::TypeScriptClient
       unsupported! unless mode == :async && context.version.to_s == @snapshot.fetch('api_version')
       source = case kind
                when :init then program(context, ['void api;'])
-               when :auth then program(context, ['void api;'], authentication(context, auth_method, auth_description))
+               when :auth then program(context, ['void api;'], authentication(context, auth_method, auth_description), errors: context.detail == :thorough)
                when :example then example(context)
                else unsupported!
                end
       { status: :code, code: source.freeze }.freeze
     rescue Unsupported, JSON::GeneratorError, EncodingError
-      # Never name fields or actions from the private SDK in public diagnostics.
-      { status: :limitation, reason: 'This sample is unavailable or incompatible with the configured TypeScript SDK.'.freeze }.freeze
+      # Never name fields or actions from the private API client in public diagnostics.
+      { status: :limitation, reason: 'This sample is unavailable or incompatible with the configured TypeScript API client.'.freeze }.freeze
+    end
+
+    def detail_levels_for(kind:, context:, result:, mode:, auth_method: nil, auth_description: nil)
+      return [:simple].freeze unless result[:status] == :code && %i[auth example].include?(kind) && mode == :async
+
+      %i[simple thorough].freeze
     end
 
     private
@@ -103,28 +109,42 @@ module HaveAPI::TypeScriptClient
     end
 
     def literal(value)
-      return "{#{value.map { |key, item| "#{key == '__proto__' ? '["__proto__"]' : literal(key)}:#{literal(item)}" }.join(',')}}" if value.is_a?(Hash)
-      return "[#{value.map { |item| literal(item) }.join(',')}]" if value.is_a?(Array)
+      if value.is_a?(Hash)
+        return '{}' if value.empty?
+
+        return "{ #{value.map { |key, item| "#{key == '__proto__' ? '["__proto__"]' : literal(key)}: #{literal(item)}" }.join(', ')} }"
+      end
+      return "[#{value.map { |item| literal(item) }.join(', ')}]" if value.is_a?(Array)
 
       JSON.generate(value).gsub("\u2028", '\\u2028').gsub("\u2029", '\\u2029')
     end
 
-    def program(context, body, auth = [])
-      version_url = context.version_url.to_s.sub(%r{/+\z}, '')
-      uri = URI.parse(version_url)
-      unsupported! unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment &&
-                          uri.path.end_with?("/v#{@snapshot.fetch('api_version')}") && Snapshot.safe_path?(uri.path)
-      dependencies = "// Configured SDK: #{@package_name}#{"@#{@package_version}" if @package_version}; runtime: haveapi-client@0.30.2."
-      lines = [dependencies, "import {AsyncClient, AsyncError} from 'haveapi-client';", "import {createClient} from #{literal(@package_name)};"]
-      unless auth.empty?
-        lines += ["import {env} from 'node:process';", '', 'function credential(name: string): string {', '  const value = env[name];',
-                  '  if (!value) throw new Error(`Missing environment variable ${name}`);', '  return value;', '}']
+    def member_access(name)
+      name.match?(/\A[$_\p{ID_Start}][$\p{ID_Continue}\u200c\u200d]*\z/u) ? ".#{name}" : "[#{literal(name)}]"
+    end
+
+    def program(context, body, auth = [], errors: false)
+      version_url = version_url(context)
+      dependencies = "// Configured API client: #{@package_name}#{"@#{@package_version}" if @package_version}."
+      runtime_imports = errors ? 'AsyncClient, AsyncError' : 'AsyncClient'
+      lines = [dependencies, "import { #{runtime_imports} } from #{literal('haveapi-client')};", "import { createClient } from #{literal(@package_name)};"]
+      lines += ['', 'async function main(): Promise<void> {']
+      operation = ["const runtime = new AsyncClient(#{literal(version_url)});"] + auth + ['const api = createClient({ execute: spec => runtime.request(spec) });'] + body
+      if errors
+        operation = ['try {'] + operation.map { |line| "  #{line}" } +
+                    ['} catch (error) {', '  if (!(error instanceof AsyncError)) throw error;',
+                     '  console.error(error.kind, error.httpStatus);', '  throw error;', '}']
       end
-      lines += ['', 'async function main(): Promise<void> {', "  const runtime = new AsyncClient(#{literal(version_url)});"]
-      lines.concat(auth.map { |line| "  #{line}" })
-      lines << '  const api = createClient({execute: spec => runtime.request(spec)});'
-      lines.concat(body.map { |line| "  #{line}" })
+      lines.concat(operation.map { |line| "  #{line}" })
       lines.push('}', '', 'main().catch(error => { throw error; });', '').join("\n")
+    end
+
+    def version_url(context)
+      value = context.version_url.to_s.sub(%r{/+\z}, '')
+      uri = URI.parse(value)
+      unsupported! unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment &&
+                          uri.path.end_with?("/v#{@snapshot.fetch('api_version')}") && Snapshot.safe_path?(uri.path)
+      value
     rescue URI::InvalidURIError
       unsupported!
     end
@@ -139,11 +159,11 @@ module HaveAPI::TypeScriptClient
       unsupported! if description && normalize(description) != live
       case method.to_s
       when 'basic'
-        ['await runtime.authenticate(\'basic\', {user: credential("HAVEAPI_USER"), password: credential("HAVEAPI_PASSWORD")});']
+        ['await runtime.authenticate("basic", { user: "user", password: "secret" });']
       when 'token'
         header = live['http_header']
         unsupported! unless header.is_a?(String) && header.match?(/\A[!#$%&'*+.^_`|~0-9A-Za-z-]+\z/) && stored['http_header'] == header
-        ['await runtime.authenticate(\'token\', {token: credential("HAVEAPI_TOKEN")});']
+        ['await runtime.authenticate("token", { token: "example-token" });']
       else unsupported!
       end
     end
@@ -186,7 +206,7 @@ module HaveAPI::TypeScriptClient
 
     def compatible_action!(action, saved, live, context)
       unsupported! unless live.is_a?(Hash)
-      expected_path = URI.parse(context.version_url.to_s).path.sub(%r{/+\z}, '') + action.fetch(:path_template)
+      expected_path = URI.parse(version_url(context)).path + action.fetch(:path_template)
       unsupported! unless live['path'] == expected_path && live['method'] == action.fetch(:method) &&
                           (live['auth'] != false) == action.fetch(:auth) && (live['blocking'] == true) == action.fetch(:blocking)
       namespace = normalized_members(normalized_members(context.description)['meta'])['namespace']
@@ -292,32 +312,46 @@ module HaveAPI::TypeScriptClient
           validate_object!(saved['output'], current['output'], value, input: false)
         end
       end
-      members = (@accessors.fetch(action.fetch(:schema_path)) + [action.fetch(:accessor_name)]).map { |name| "[#{literal(name)}]" }.join
+      members = (@accessors.fetch(action.fetch(:schema_path)) + [action.fetch(:accessor_name)]).map { |name| member_access(name) }.join
       call = "api#{members}"
       call += "(#{literal(options) unless options.empty?})"
       if sample['status'] == false || (sample['http_status'].is_a?(Integer) && sample['http_status'] >= 400)
         body = ['try {', "  await #{call};", '  throw new Error("Expected the documented request to fail");',
                 '} catch (error) {', '  if (!(error instanceof AsyncError)) throw error;',
-                '  void [error.kind, error.httpStatus, error.errors, error.envelope, error.response];', '}']
+                '  console.error(error.kind, error.httpStatus);']
+        body << '  void [error.errors, error.envelope, error.response];' if context.detail == :thorough
+        body << '}'
+        failure = true
       else
-        body = ["const result = await #{call};", 'void [result.data, result.meta, result.envelope, result.httpStatus];']
-        body.concat(output_lines(action, response))
+        body = ["const result = await #{call};"]
+        body << 'void [result.data, result.meta, result.envelope, result.httpStatus];' if context.detail == :thorough
+        body.concat(output_lines(action, response, thorough: context.detail == :thorough))
       end
       body << '// Request success does not establish completion of a server-side operation.' if action.fetch(:blocking)
-      program(context, body, action_authentication(action, context))
+      auth = action_authentication(action, context)
+      if context.detail == :thorough
+        return program(context, body, auth, errors: true)
+      end
+
+      imports = failure ? ["import { AsyncError } from #{literal('haveapi-client')};", ''] : []
+      (imports + ['// Requires an initialized api and an async context.'] + body + ['']).join("\n")
     end
 
-    def output_lines(action, response)
+    def output_lines(action, response, thorough:)
       return [] unless response && action[:output]
 
       list = action[:output][:layout].end_with?('_list')
       values = list ? response : [response]
       names = values.flat_map(&:keys).uniq
       body = names.flat_map do |name|
-        expression = "item[#{literal(name)}]"
-        ["const value#{names.index(name)}: unknown = #{expression};", "if (value#{names.index(name)} !== null && value#{names.index(name)} !== undefined) void value#{names.index(name)};"]
+        expression = "#{list || thorough ? 'item' : 'result.data'}#{member_access(name)}"
+        next ["console.log(#{expression});"] unless thorough
+
+        ["const value#{names.index(name)}: unknown = #{expression};", "if (value#{names.index(name)} !== null && value#{names.index(name)} !== undefined) console.log(value#{names.index(name)});"]
       end
-      list ? ['for (const item of result.data) {'] + body.map { |line| "  #{line}" } + ['}'] : ['const item = result.data;'] + body
+      return ['for (const item of result.data) {'] + body.map { |line| "  #{line}" } + ['}'] if list
+
+      (thorough ? ['const item = result.data;'] : []) + body
     end
   end
 end

data/lib/haveapi/typescript_client/formatter.rb

@@ -0,0 +1,57 @@
+require 'digest'
+require 'fileutils'
+require 'open3'
+require 'tmpdir'
+
+module HaveAPI::TypeScriptClient
+  # Format only the validated emission tree, before the generator hashes it.
+  class Formatter
+    VERSION = '3.9.10'.freeze
+    CONFIG = File.expand_path('prettier.json', __dir__).freeze
+
+    def initialize
+      @executable = ENV.fetch('PRETTIER', 'prettier')
+      @executable = File.expand_path(@executable) if @executable.include?(File::SEPARATOR)
+    end
+
+    def version
+      actual = capture('--version').strip
+      raise Error, "Prettier #{VERSION} is required; found #{actual.inspect}" unless actual == VERSION
+
+      actual
+    end
+
+    def provenance
+      { 'name' => 'prettier', 'version' => VERSION, 'config_sha256' => Digest::SHA256.file(CONFIG).hexdigest }
+    end
+
+    def format(files)
+      version
+      Dir.mktmpdir('haveapi-typescript-format-') do |directory|
+        files.each do |path, content|
+          target = File.join(directory, path)
+          FileUtils.mkdir_p(File.dirname(target))
+          File.write(target, content)
+        end
+        capture('--config', CONFIG, '--no-editorconfig', '--ignore-path', File::NULL,
+                '--parser', 'typescript', '--write', '**/*.ts', chdir: directory)
+        files.to_h do |path, _content|
+          [path, File.read(File.join(directory, path), encoding: 'UTF-8')]
+        end
+      end
+    rescue SystemCallError => e
+      raise Error, "Prettier formatting failed: #{e.message}"
+    end
+
+    private
+
+    def capture(*, **)
+      stdout, stderr, status = Open3.capture3(@executable, *, **)
+      raise Error, "Prettier failed: #{stderr.strip}" unless status.success?
+
+      stdout
+    rescue SystemCallError => e
+      raise Error, "Unable to run Prettier #{@executable.inspect}: #{e.message}"
+    end
+  end
+end

data/lib/haveapi/typescript_client/generator.rb

@@ -11,7 +11,7 @@ module HaveAPI::TypeScriptClient
 
     def self.source_files
       Dir.chdir(ROOT) do
-        Dir['bin/**/*', 'lib/**/*.rb', 'template/**/*', 'Gemfile', '*.gemspec', 'Rakefile']
+        Dir['bin/**/*', 'lib/**/*.{rb,json}', 'template/**/*', 'Gemfile', '*.gemspec', 'Rakefile']
           .select { |path| File.file?(path) }.sort
       end
     end
@@ -41,12 +41,16 @@ module HaveAPI::TypeScriptClient
       require_relative 'emitter'
       files = Emitter.new(@ir, @config).files
       validate_files(files)
+      require_relative 'formatter'
+      formatter = Formatter.new
+      files = formatter.format(files)
+      validate_files(files)
       manifest = {
         'owner' => OWNER, 'format' => 1, 'generator_version' => VERSION,
         'generator_source_sha256' => self.class.source_digest,
         'schema_sha256' => Snapshot.sha256(@schema), 'api_version' => @schema.fetch('api_version'),
         'protocol_version' => @schema.fetch('protocol_version'), 'profile' => @schema.fetch('profile'),
-        'config' => @config.transform_keys(&:to_s), 'coverage' => coverage,
+        'config' => @config.transform_keys(&:to_s), 'formatter' => formatter.provenance, 'coverage' => coverage,
         'files' => files.sort.to_h.transform_values { |content| Digest::SHA256.hexdigest(content) }
       }
       candidate = files.merge(OWNER_FILE => Snapshot.canonical(manifest))

data/lib/haveapi/typescript_client/prettier.json

@@ -0,0 +1 @@
+{}

data/lib/haveapi/typescript_client/version.rb

@@ -1,5 +1,5 @@
 module HaveAPI
   module TypeScriptClient
-    VERSION = '0.31.2'.freeze
+    VERSION = '0.32.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi-typescript-client
 version: !ruby/object:Gem::Version
-  version: 0.31.2
+  version: 0.32.0
 platform: ruby
 authors:
 - Jakub Skokan
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.31.2
+        version: 0.32.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.31.2
+        version: 0.32.0
 executables:
 - haveapi-typescript-client
 extensions: []
@@ -39,9 +39,11 @@ files:
 - lib/haveapi/typescript_client/cli.rb
 - lib/haveapi/typescript_client/documentation.rb
 - lib/haveapi/typescript_client/emitter.rb
+- lib/haveapi/typescript_client/formatter.rb
 - lib/haveapi/typescript_client/generator.rb
 - lib/haveapi/typescript_client/ir.rb
 - lib/haveapi/typescript_client/naming.rb
+- lib/haveapi/typescript_client/prettier.json
 - lib/haveapi/typescript_client/snapshot.rb
 - lib/haveapi/typescript_client/version.rb
 - template/action.ts.erb