camille 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5779c76d0ca3c695e1e15d0870d94be5739449f7ad1b9422ab9944d139f3a6d1
-  data.tar.gz: 855906b19324060e4fb8578451e1fd77f692918f6722a81b9f3fbdc5cbf48fd3
+  metadata.gz: 1d5aa31349909cebc62309be91631d632419b925d9a6ded594485dfa204e9170
+  data.tar.gz: d1b1cb24a630a0c109fc1042636372cf193dd135f1ef17784f3907c1a169502e
 SHA512:
-  metadata.gz: e555aebf740ecd06dcf96928a3aeafe414430a7d439a83679da90d2e60e23a97cd28bc583a473ddab76c60275e31668b76f9220ca2278c21ecceb8f2f11743fa
-  data.tar.gz: 00bf823aa9f394c1198cd492f42cd716b8bd59c08fe7e704df64aa92cdb927198ad87761f867de9b59153cba96490190292296755ef1642bd9c759820b00ecc0
+  metadata.gz: 7d65f32be6f7d8beee2d22b9d5cf5ed4fc84fa91c925605c6aa0be09d51475211ddbee5e23f321892d0f46fa59878af2d9753e3daac7c1e62f2ccf285e8147b6
+  data.tar.gz: f2195c3c54f6c571abeb2fa3b541160f734c1ecee6adfaec4bc4025ad0be820ae4235028a3c91427aec3c7cbdcc4ba19ba5f7a3e7cb530a3e943913b57955a78

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    camille (0.3.0)
+    camille (0.4.0)
       rails (>= 6.1, < 8)
 
 GEM

data/README.md

@@ -1,8 +1,31 @@
 # Camille
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/camille`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Why?
 
-TODO: Delete this and the text above, and describe your gem
+Traditionally, the JSON response from a Rails API server isn't typed. So even if we have TypeScript at the front-end, we still have little guarantee that our back-end would return the correct type and structure of data. In order to eliminate type mismatch between both ends, Camille provides a syntax for you to define type schema for your Rails API, and uses these schemas to generate the TypeScript functions for calling the API.
+
+For example, an endpoint defined in Ruby, where `data` is a controller action,
+
+```ruby
+get :data do
+  params(
+    id: Number
+  )
+  response(
+    name: String
+  )
+end
+```
+
+will become a function in TypeScript:
+
+```typescript
+data(params: {id: number}): Promise<{name: string}>
+```
+
+Therefore, if the front-end requests the API by calling `data`, we have guarantee that `id` is presented in `params`, and Camille will require the response to contain a string `name`, so the front-end can receive the correct type of data.
+
+By using these request functions, we also don't need to know about HTTP verbs and paths. It's impossible to have unrecognized routes, since Camille will make sure that each function handled by the correct Rails action.
 
 ## Installation
 
@@ -14,22 +37,208 @@ gem 'camille'
 
 And then execute:
 
-    $ bundle install
+```bash
+bundle install
+bundle exec rails g camille:install
+```
 
-Or install it yourself as:
+## Usage
 
-    $ gem install camille
+### Schemas
 
-## Usage
+A schema defines the type of `params` and `response` for a controller action. The following commands will generate schema definition files in `config/camille/schemas`.
 
-TODO: Write usage instructions here
+```bash
+# to generate a schema for ProductsController
+bundle exec rails g camille:schema products
+# to generate a schema for Api::ProductController
+bundle exec rails g camille:schema api/products
+```
 
-## Development
+An example of schema definition:
+
+```ruby
+using Camille::Syntax
+
+class Camille::Schemas::Api::Products < Camille::Schema
+  include Camille::Types
+
+  get :data do
+    params(
+      id: Number
+    )
+    response(
+      name: String
+    )
+  end
+end
+```
+
+The `Api::Products` schema defines one endpoint `data` and its params and response type. This endpoint corresponds to the `data` action on `Api::ProductsController`. Inside the action, you can assume that `params[:id]` is a number, and you will need to `render json: {name: 'some string'}` in order to pass the typecheck.
+
+When generating TypeScript request functions, the `data` endpoint will become a function having the following signature:
+
+```typescript
+data(params: {id: number}): Promise<{name: string}>
+```
+
+Therefore, the front-end user is required to provide an `id` when they call this function. And they can expect to get a `name` from the response of this request. There are no more type mismatch between both ends.
+
+Camille will automatically add a Rails route for each endpoint. You don't need to do anything other than having the schema file in place.
+
+When defining an endpoint, you can also use `post` instead of `get` for non-idempotent requests. However, no other HTTP verbs are supported, because verbs in RESTful like `patch` and `delete` indicate what we do on resources, but in RPC-style design each request is merely a function call that does not concern RESTful resources.
+
+### Custom types
+
+In addition to primitive types, you can define custom types in Camille. The following commands will generate type definition files in `config/camille/types`.
+
+```bash
+# to generate a type named Product
+rails g camille:type product
+# to generate a type named Nested::Product
+rails g camille:type nested/product
+```
+
+An example of custom type definition:
+
+```ruby
+using Camille::Syntax
+
+class Camille::Types::Product < Camille::Type
+  include Camille::Types
+
+  alias_of(
+    id: Number,
+    name: String
+  )
+end
+```
+
+Each custom type is considered a type alias in TypeScript. And `alias_of` defines what this type is aliasing. In this case, the `Product` type is an alias of an object type having fields `id` as `Number` and `name` as `String`. When generating TypeScript, it will be converted to the following:
+
+```typescript
+type Product = {id: number, name: string}
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Available syntax for types
+
+Camille supports most of the type syntax in TypeScript. Below is a list of types that you can use in type and schema definition.
+
+```ruby
+params(
+  # primitive types in TypeScript
+  number: Number,
+  string: String,
+  boolean: Boolean,
+  null: Null,
+  undefined: Undefined,
+  any: Any,
+  # an array type is a type name followed by '[]'
+  array: Number[],
+  # an object type looks like hash
+  object: {
+    field: Number
+  },
+  # an array of objects also works
+  object_array: {
+    field: Number
+  }[]
+  # a union type is two types connected by '|'
+  union: Number | String,
+  # a tuple type is several types put inside '[]'
+  tuple: [Number, String, Boolean],
+  # a field followed by '?' is optional, the same as in TypeScript
+  optional?: Number,
+  # literal types
+  number_literal: 1,
+  string_literal: 'hello',
+  # a custom type we defined above
+  product: Product
+)
+```
+
+String literal types and probably enums are planned for the future.
+
+### TypeScript generation
+
+After you have your types and schemas in place, you can visit `/camille/endpoints.ts` in development environment to have the TypeScript request functions generated.
+
+An example from our previously defined type and schema will be:
+
+```typescript
+import request from './request'
+
+export type Product = {id: number, name: string}
+
+export default {
+  api: {
+    data(params: {id: number}): Promise<{name: string}> {
+      return request('get', '/api/products/data', params)
+    }
+  }
+}
+```
+
+The first line of `import` is configurable as `config.ts_header` in `config/camille/configuration.rb`. You would need to implement a `request` function that performs the HTTP request.
+
+### Conversion between camelCase and snake_case
+
+In TypeScript world, people usually use camelCase to name functions and variables, while in Ruby the convention is to use snake_case. Camille will automatically convert between these two when processing request.
+
+For example,
+
+```ruby
+get :special_data do
+  params(
+    long_id: Number
+  )
+  response(
+    long_name: String
+  )
+end
+```
+
+will have TS signature:
+
+```typescript
+specialData(params: {longId: number}): Promise<{longName: string}>
+```
+
+In the Rails action you still use `params[:long_id]` to access the parameter and return `long_name` in response.
+
+### Typechecking
+
+If a controller action has a corresponding schema, Camille will raise an error if the returned JSON doesn't match the response type specified in the schema.
+
+For example for
+```ruby
+response(
+  object: {
+    array: Number[]
+  }
+)
+```
+
+if we return such a JSON in our action
+```ruby
+render json: {
+  object: {
+    array: [1, 2, '3']
+  }
+}
+```
+
+Camille will print the following error:
+```
+object:
+  array:
+    [2]: Expected number, got "3".
+```
+
+## Development
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Run tests with `bundle exec rake`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/camille.
+Bug reports and pull requests are welcome on GitHub at https://github.com/onyxblade/camille.

data/lib/camille/basic_type.rb

@@ -24,13 +24,18 @@ module Camille
     end
 
     def self.instance value
-      if value.is_a? ::Hash
+      case
+      when value.is_a?(::Hash)
         Camille::Types::Object.new(value)
-      elsif value.is_a? ::Array
+      when value.is_a?(::Array)
         Camille::Types::Tuple.new(value)
-      elsif value.is_a? Camille::BasicType
+      when value.is_a?(Integer) || value.is_a?(Float)
+        Camille::Types::NumberLiteral.new(value)
+      when value.is_a?(::String)
+        Camille::Types::StringLiteral.new(value)
+      when value.is_a?(Camille::BasicType)
         value
-      elsif value.is_a?(Class) && value < Camille::BasicType && value.directly_instantiable?
+      when value.is_a?(Class) && value < Camille::BasicType && value.directly_instantiable?
         value.new
       else
         raise InvalidTypeError.new("#{value} cannot be converted to a type instance.")

data/lib/camille/controller_extension.rb

@@ -17,8 +17,9 @@ module Camille
         if value = render_options[:json]
           error = endpoint.response_type.check(value)
           if error
-            Camille::TypeErrorPrinter.new(error).print
-            raise TypeError.new("Type check failed for response.")
+            string_io = StringIO.new
+            Camille::TypeErrorPrinter.new(error).print(string_io)
+            raise TypeError.new("\nType check failed for response.\n#{string_io.string}")
           else
             if value.is_a? Hash
               value.deep_transform_keys!{|k| k.to_s.camelize(:lower)}

data/lib/camille/generators/install_generator.rb

@@ -10,12 +10,12 @@ module Camille
         copy_file "configuration.rb", "config/camille/configuration.rb"
       end
 
-      def copy_type_example
-        copy_file "type_example.rb", "config/camille/types/example.rb"
+      def create_types_folder
+        copy_file ".keep", "config/camille/types/.keep"
       end
 
-      def copy_schema_example
-        copy_file "schema_example.rb", "config/camille/schemas/examples.rb"
+      def create_schemas_folder
+        copy_file ".keep", "config/camille/schemas/.keep"
       end
 
     end

data/lib/camille/generators/templates/schema_template.erb

@@ -1,4 +1,4 @@
-using Camille::CoreExt
+using Camille::Syntax
 
 class Camille::Schemas::<%= class_name %> < Camille::Schema
   include Camille::Types

data/lib/camille/generators/templates/type_template.erb

@@ -1,9 +1,9 @@
-using Camille::CoreExt
+using Camille::Syntax
 
 class Camille::Types::<%= class_name %> < Camille::Type
   include Camille::Types
 
-  alias_of(
-    # id: Number
-  )
+  # alias_of(
+  #   id: Number
+  # )
 end

data/lib/camille/syntax.rb

@@ -0,0 +1,75 @@
+module Camille
+  module Syntax
+    module NULL_VALUE; end
+
+    refine ::Hash do
+      def [] key = NULL_VALUE
+        if key == NULL_VALUE
+          Camille::Types::Object.new(self)[]
+        else
+          super
+        end
+      end
+
+      def | other
+        Camille::Types::Union.new(Camille::Types::Object.new(self), other)
+      end
+    end
+
+    refine ::Array do
+      def [] key = NULL_VALUE
+        if key == NULL_VALUE
+          Camille::Types::Tuple.new(self)[]
+        else
+          super
+        end
+      end
+
+      def | other
+        Camille::Types::Union.new(Camille::Types::Tuple.new(self), other)
+      end
+    end
+
+    refine Integer do
+      def [] key = NULL_VALUE
+        if key == NULL_VALUE
+          Camille::Types::NumberLiteral.new(self)[]
+        else
+          super
+        end
+      end
+
+      def | other
+        Camille::Types::Union.new(Camille::Types::NumberLiteral.new(self), other)
+      end
+    end
+
+    refine Float do
+      def [] key = NULL_VALUE
+        if key == NULL_VALUE
+          Camille::Types::NumberLiteral.new(self)[]
+        else
+          super
+        end
+      end
+
+      def | other
+        Camille::Types::Union.new(Camille::Types::NumberLiteral.new(self), other)
+      end
+    end
+
+    refine ::String do
+      def [] key = NULL_VALUE
+        if key == NULL_VALUE
+          Camille::Types::StringLiteral.new(self)[]
+        else
+          super
+        end
+      end
+
+      def | other
+        Camille::Types::Union.new(Camille::Types::StringLiteral.new(self), other)
+      end
+    end
+  end
+end

data/lib/camille/type_error_printer.rb

@@ -18,9 +18,9 @@ module Camille
       def print_composite_error io, error, indentation
         error.components.each do |key, error|
           if error.basic?
-            io.puts ' ' * indentation + "#{key}: #{error.message}"
+            io.puts "\u00A0" * indentation + "#{key}: #{error.message}"
           else
-            io.puts ' ' * indentation + "#{key}:"
+            io.puts "\u00A0" * indentation + "#{key}:"
             print_composite_error io, error, indentation + 2
           end
         end

data/lib/camille/types/number.rb

@@ -4,7 +4,7 @@ module Camille
 
       def check value
         unless value.is_a?(Integer) || value.is_a?(Float)
-          Camille::TypeError.new("Expected number, got #{value.inspect}.")
+          Camille::TypeError.new("Expected an integer or a float, got #{value.inspect}.")
         end
       end
 

data/lib/camille/types/number_literal.rb

@@ -0,0 +1,25 @@
+module Camille
+  module Types
+    class NumberLiteral < Camille::BasicType
+      class ArgumentError < ::ArgumentError; end
+
+      def initialize value
+        if value.is_a?(Integer) || value.is_a?(Float)
+          @value = value
+        else
+          raise ArgumentError.new("Expecting an integer or a float, got #{value.inspect}")
+        end
+      end
+
+      def check value
+        unless value == @value
+          Camille::TypeError.new("Expected number literal #{@value.inspect}, got #{value.inspect}.")
+        end
+      end
+
+      def literal
+        @value.to_s
+      end
+    end
+  end
+end

data/lib/camille/types/string_literal.rb

@@ -0,0 +1,25 @@
+module Camille
+  module Types
+    class StringLiteral < Camille::BasicType
+      class ArgumentError < ::ArgumentError; end
+
+      def initialize value
+        if value.is_a?(::String)
+          @value = value
+        else
+          raise ArgumentError.new("Expecting a string, got #{value.inspect}")
+        end
+      end
+
+      def check value
+        unless value == @value
+          Camille::TypeError.new("Expected string literal #{@value.inspect}, got #{value.inspect}.")
+        end
+      end
+
+      def literal
+        @value.inspect
+      end
+    end
+  end
+end

data/lib/camille/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Camille
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/camille.rb

@@ -15,10 +15,12 @@ require_relative "camille/types/undefined"
 require_relative "camille/types/union"
 require_relative "camille/types/tuple"
 require_relative "camille/types/any"
+require_relative "camille/types/number_literal"
+require_relative "camille/types/string_literal"
 require_relative "camille/type"
 require_relative "camille/type_error"
 require_relative "camille/type_error_printer"
-require_relative "camille/core_ext"
+require_relative "camille/syntax"
 require_relative "camille/endpoint"
 require_relative "camille/schema"
 require_relative "camille/schemas"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: camille
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - 辻彩
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-03-16 00:00:00.000000000 Z
+date: 2023-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -49,14 +49,12 @@ files:
 - lib/camille/code_generator.rb
 - lib/camille/configuration.rb
 - lib/camille/controller_extension.rb
-- lib/camille/core_ext.rb
 - lib/camille/endpoint.rb
 - lib/camille/generators/install_generator.rb
 - lib/camille/generators/schema_generator.rb
+- lib/camille/generators/templates/.keep
 - lib/camille/generators/templates/configuration.rb
-- lib/camille/generators/templates/schema_example.rb
 - lib/camille/generators/templates/schema_template.erb
-- lib/camille/generators/templates/type_example.rb
 - lib/camille/generators/templates/type_template.erb
 - lib/camille/generators/type_generator.rb
 - lib/camille/line.rb
@@ -65,6 +63,7 @@ files:
 - lib/camille/railtie.rb
 - lib/camille/schema.rb
 - lib/camille/schemas.rb
+- lib/camille/syntax.rb
 - lib/camille/type.rb
 - lib/camille/type_error.rb
 - lib/camille/type_error_printer.rb
@@ -74,8 +73,10 @@ files:
 - lib/camille/types/boolean.rb
 - lib/camille/types/null.rb
 - lib/camille/types/number.rb
+- lib/camille/types/number_literal.rb
 - lib/camille/types/object.rb
 - lib/camille/types/string.rb
+- lib/camille/types/string_literal.rb
 - lib/camille/types/tuple.rb
 - lib/camille/types/undefined.rb
 - lib/camille/types/union.rb

data/lib/camille/core_ext.rb

@@ -1,33 +0,0 @@
-module Camille
-  module CoreExt
-    module NULL_VALUE; end
-
-    refine ::Hash do
-      def [] key = NULL_VALUE
-        if key == NULL_VALUE
-          Camille::Types::Object.new(self)[]
-        else
-          super
-        end
-      end
-
-      def | other
-        Camille::Types::Union.new(Camille::Types::Object.new(self), other)
-      end
-    end
-
-    refine ::Array do
-      def [] key = NULL_VALUE
-        if key == NULL_VALUE
-          Camille::Types::Tuple.new(self)[]
-        else
-          super
-        end
-      end
-
-      def | other
-        Camille::Types::Union.new(Camille::Types::Tuple.new(self), other)
-      end
-    end
-  end
-end

data/lib/camille/generators/templates/schema_example.rb

@@ -1,35 +0,0 @@
-using Camille::CoreExt
-
-class Camille::Schemas::Examples < Camille::Schema
-  include Camille::Types
-
-  get :find do
-    params(
-      id: Number
-    )
-
-    response(
-      example?: Example
-    )
-  end
-
-  get :list do
-    response(
-      examples: Example[]
-    )
-  end
-
-  post :update do
-    params(
-      id: Number,
-      example: Example
-    )
-
-    response(
-      success: Boolean,
-      errors: {
-        message: String
-      }[]
-    )
-  end
-end

data/lib/camille/generators/templates/type_example.rb

@@ -1,10 +0,0 @@
-using Camille::CoreExt
-
-class Camille::Types::Example < Camille::Type
-  include Camille::Types
-
-  alias_of(
-    id: Number,
-    name: String,
-  )
-end