Update docs

- Add concept of collections
- Add page for Heterogeneous Collections
- Update Attributes page with new Types paradigm
- Move Deferred Values into its own page
- Update VitePress

Author: tobyzerner

README.md

@@ -43,6 +43,7 @@ use Tobyz\JsonApiServer\Laravel\EloquentResource;
 use Tobyz\JsonApiServer\Laravel\Filter;
 use Tobyz\JsonApiServer\Endpoint;
 use Tobyz\JsonApiServer\Schema\Field;
+use Tobyz\JsonApiServer\Schema\Type;
 use Tobyz\JsonApiServer\JsonApi;
 
 class UsersResource extends EloquentResource
@@ -71,13 +72,14 @@ class UsersResource extends EloquentResource
     public function fields(): array
     {
         return [
-            Field\Str::make('name')
+            Field\Attribute::make('name')
+                ->type(Type\Str::make())
                 ->writable()
                 ->required(),
 
-            Field\HasOne::make('address')->includable(),
+            Field\ToOne::make('address')->includable(),
 
-            Field\HasMany::make('friends')
+            Field\ToMany::make('friends')
                 ->type('users')
                 ->includable(),
         ];

docs/.vitepress/config.ts

@@ -14,22 +14,22 @@ export default defineConfig({
                     { text: 'Introduction', link: '/' },
                     { text: 'Installation', link: '/install' },
                     { text: 'Handling Requests', link: '/requests' },
-                    { text: 'Defining Resources', link: '/resources' },
                     { text: 'Laravel Integration', link: '/laravel' },
                 ],
             },
             {
-                text: 'Schema',
+                text: 'Resources',
                 items: [
-                    { text: 'Fields', link: '/fields' },
+                    { text: 'Defining Resources', link: '/resources' },
+                    { text: 'Defining Fields', link: '/fields' },
                     { text: 'Attributes', link: '/attributes' },
                     { text: 'Relationships', link: '/relationships' },
                 ],
             },
             {
                 text: 'Endpoints',
                 items: [
-                    { text: 'List', link: '/list' },
+                    { text: 'Index', link: '/list' },
                     { text: 'Create', link: '/create' },
                     { text: 'Show', link: '/show' },
                     { text: 'Update', link: '/update' },
@@ -40,9 +40,14 @@ export default defineConfig({
                 text: 'Advanced',
                 items: [
                     { text: 'Context', link: '/context' },
+                    { text: 'Deferred Values', link: '/deferred' },
                     { text: 'Error Handling', link: '/errors' },
                     { text: 'Extensions', link: '/extensions' },
-                    { text: 'OpenAPI', link: '/openapi' },
+                    {
+                        text: 'Heterogeneous Collections',
+                        link: '/collections',
+                    },
+                    { text: 'OpenAPI Definitions', link: '/openapi' },
                 ],
             },
         ],
@@ -59,7 +64,4 @@ export default defineConfig({
                 'https://github.com/tobyzerner/json-api-server/edit/main/docs/:path',
         },
     },
-    markdown: {
-        theme: 'nord',
-    },
 });

docs/.vitepress/theme/custom.css

@@ -1,18 +1,8 @@
 :root {
-    --vp-c-brand: #0000ff;
+    --vp-c-brand-1: #0000ff;
+    --vp-c-brand-2: var(--vp-c-brand-1);
 }
 
 .dark {
-    --vp-c-brand: #8a8aff;
-}
-
-.vp-doc h1 + p {
-    font-size: 140%;
-    line-height: 1.5;
-}
-
-.vp-doc a:not(.header-anchor) {
-    text-decoration: underline;
-    text-decoration-style: solid;
-    font-weight: inherit;
+    --vp-c-brand-1: #8a8aff;
 }

docs/attributes.md

@@ -1,103 +1,90 @@
 # Attributes
 
-## Generic Attributes
-
-You can define a generic attribute on your resource using the `Attribute` class.
-No specific serialization, deserialization, or validation will be performed:
+You can define a attribute field on your resource using the `Attribute` class.
 
 ```php
-use Tobyz\JsonApiServer\Field\Attribute;
+use Tobyz\JsonApiServer\Schema\Field\Attribute;
 
 Attribute::make('title');
 ```
 
-## Typed Attributes
+## Attribute Types
 
-json-api-server includes a selection of typed attribute implementations to match
-the data types in the
+Attributes can be configured with a type to automatically perform appropriate
+serialization, deserialization, and validation. json-api-server includes a
+selection of type implementations to match the data types in the
 [OpenAPI specification](https://swagger.io/docs/specification/data-models/data-types/).
 
 ### Boolean
 
-The `Boolean` attribute serializes values to booleans, and performs validation
-to ensure that incoming values are booleans.
+The `Boolean` type serializes values to booleans, and performs validation to
+ensure that incoming values are booleans.
 
 ```php
-use Tobyz\JsonApiServer\Field\Boolean;
+use Tobyz\JsonApiServer\Schema\Type\Boolean;
 
-Boolean::make('active');
+Attribute::make('active')->type(Boolean::make());
 ```
 
 ### Date and DateTime
 
-The `Date` and `DateTime` attributes serialize and deserialize values between
-strings using RFC 3339 notation and `DateTime` objects, and perform validation
-to ensure that incoming values match this format.
+The `Date` and `DateTime` types serialize and deserialize values between strings
+using RFC 3339 notation and `DateTime` objects, and perform validation to ensure
+that incoming values match this format.
 
 ```php
-use Tobyz\JsonApiServer\Field\Date;
-use Tobyz\JsonApiServer\Field\DateTime;
-
-Date::make('dob');
-DateTime::make('publishedAt');
-```
-
-### BooleanDateTime
-
-The `BooleanDateTime` attribute behaves like the `Boolean` attribute, except
-that before setting the value to the model, a `true` value is set as the current
-date, and a `false` value is set as `null`. This can be used to represent a
-field that is stored internally as a timestamp as a boolean in the API.
+use Tobyz\JsonApiServer\Schema\Type\Date;
+use Tobyz\JsonApiServer\Schema\Type\DateTime;
 
-```php
-use Tobyz\JsonApiServer\Field\DateTime;
-
-BooleanDateTime::make('isDeleted')
-    ->property('deleted_at')
-    ->writable();
+Attribute::make('dob')->type(Date::make());
+Attribute::make('publishedAt')->type(DateTime::make());
 ```
 
 ### Number and Integer
 
-The `Number` attribute serializes values to floats, and performs validation to
-ensure that incoming values are numeric.
+The `Number` type serializes values to floats, and performs validation to ensure
+that incoming values are numeric.
 
 ```php
-use Tobyz\JsonApiServer\Field\Number;
+use Tobyz\JsonApiServer\Schema\Type\Number;
 
-Number::make('weight');
+Attribute::make('weight')->type(Number::make());
 ```
 
-The `Integer` attribute serializes values to integers, and performs validation
-to ensure that incoming values are integers.
+The `Integer` type serializes values to integers, and performs validation to
+ensure that incoming values are integers.
 
 ```php
-use Tobyz\JsonApiServer\Field\Integer;
+use Tobyz\JsonApiServer\Schema\Type\Integer;
 
-Integer::make('commentCount');
+Attribute::make('commentCount')->type(Integer::make());
 ```
 
 #### Minimum and Maximum
 
 Use the `minimum` and `maximum` methods to specify the range of possible values.
 
 ```php
-use Tobyz\JsonApiServer\Field\Number;
+use Tobyz\JsonApiServer\Schema\Type\Number;
 
-Number::make('number')
-    ->minimum(1)
-    ->maximum(20);
+Attribute::make('number')->type(
+    Number::make()
+        ->minimum(1)
+        ->maximum(20),
+);
 ```
 
 By default, these values are included in the range. To exclude the boundary
 values, you can add a second argument:
 
 ```php
-use Tobyz\JsonApiServer\Field\Number;
+use Tobyz\JsonApiServer\Schema\Type\Number;
 
-Number::make('number')
-    ->minimum(1, exclusive: true)
-    ->maximum(20, exclusive: true);
+Attribute::make('number')->type(
+    Number::make()
+        ->minimum(1, exclusive: true)
+        ->maximum(20, exclusive: true),
+);
 ```
 
 #### Multiples
@@ -106,38 +93,40 @@ Use the `multipleOf` method to specify that a number must be the multiple of
 another number:
 
 ```php
-use Tobyz\JsonApiServer\Field\Integer;
+use Tobyz\JsonApiServer\Schema\Type\Integer;
 
-Integer::make('number')->multipleOf(10);
+Attribute::make('number')->type(Integer::make()->multipleOf(10));
 ```
 
 ### String
 
-The `Str` attribute serializes values to strings, and performs validation to
-ensure that incoming values are strings.
+The `Str` type serializes values to strings, and performs validation to ensure
+that incoming values are strings.
 
 ```php
-use Tobyz\JsonApiServer\Field\Str;
+use Tobyz\JsonApiServer\Schema\Type\Str;
 
-Str::make('name');
+Attribute::make('name')->type(Str::make());
 ```
 
 #### `minLength` and `maxLength`
 
 String length can be restricted using the `minLength` and `maxLength` methods:
 
 ```php
-Str::make('name')
-    ->minLength(3)
-    ->maxLength(20);
+Attribute::make('name')->type(
+    Str::make()
+        ->minLength(3)
+        ->maxLength(20),
+);
 ```
 
 #### `enum`
 
 You can restrict the string to a set of possible values using the `enum` method.
 
 ```php
-Str::make('status')->enum(['to do', 'doing', 'done']);
+Attribute::make('status')->type(Str::make()->enum(['to do', 'doing', 'done']));
 ```
 
 #### `pattern`
@@ -147,7 +136,7 @@ You can also validate the string against a regular expression using the
 and are case-sensitive.
 
 ```php
-Str::make('ssn')->pattern('^\d{3}-\d{2}-\d{4}$');
+Attribute::make('ssn')->type(Str::make()->pattern('^\d{3}-\d{2}-\d{4}$'));
 ```
 
 #### `format`
@@ -157,10 +146,28 @@ You can mark strings with a
 to serve as a hint in your OpenAPI definition:
 
 ```php
-Str::make('email')->format('email');
+Attribute::make('email')->type(Str::make()->format('email'));
 ```
 
 Note that this will not add any additional behaviour (like serialization and
 validation) to the field – you will need to implement this yourself. For the
 `date` and `date-time` formats, you should use the
-[Date and DateTime](#date-and-datetime) attributes instead.
+[Date and DateTime](#date-and-datetime) types instead.
+
+## Special Attributes
+
+### BooleanDateTime
+
+The `BooleanDateTime` attribute subclass behaves like a `Boolean`-typed
+attribute, except that before setting the value to the model, a `true` value is
+set as the current date, and a `false` value is set as `null`. This can be used
+to represent a field that is stored internally as a timestamp as a boolean in
+the API.
+
+```php
+use Tobyz\JsonApiServer\Schema\Field\BooleanDateTime;
+
+BooleanDateTime::make('isDeleted')
+    ->property('deleted_at')
+    ->writable();
+```