yayson 3.0.0 → 4.0.0

package/skill/yayson/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: yayson
+description: Serialize and parse JSON API data with yayson. Use when writing Presenters, setting up Stores (standard or legacy), or working with yayson relationships and schema validation.
+---
+
+# YAYSON
+
+## Setup
+
+```typescript
+// Standard (JSON API 1.0)
+import yayson from 'yayson'
+const { Presenter, Store } = yayson()
+
+// Legacy (pre-1.0 format)
+import yayson from 'yayson/legacy'
+const { Presenter, Store } = yayson()
+
+// Sequelize adapter
+const { Presenter } = yayson({ adapter: 'sequelize' })
+
+// Utility helpers for reading symbols off store models
+import { getType, getMeta, getLinks, getRelationshipLinks, getRelationshipMeta } from 'yayson/utils'
+```
+
+## Presenters
+
+Presenters serialize JS objects into JSON API documents. Subclass Presenter and set `static type`.
+
+### Basic presenter
+
+```typescript
+class UserPresenter extends Presenter {
+  static type = 'users'
+}
+
+UserPresenter.render({ id: 1, name: 'Ada' })
+// { data: { type: 'users', id: '1', attributes: { name: 'Ada' } } }
+```
+
+### Field filtering
+
+```typescript
+class UserPresenter extends Presenter {
+  static type = 'users'
+  static fields = ['name', 'email'] // whitelist, excludes everything else
+}
+```
+
+### Relationships
+
+Return a map of property name to Presenter class from `relationships()`. Related data goes into `included`.
+
+```typescript
+class WheelPresenter extends Presenter {
+  static type = 'wheels'
+}
+
+class BikePresenter extends Presenter {
+  static type = 'bikes'
+  relationships() {
+    return { wheels: WheelPresenter }
+  }
+}
+
+BikePresenter.render({ id: 1, wheels: [{ id: 10 }, { id: 11 }] })
+// data.relationships.wheels.data = [{ type: 'wheels', id: '10' }, ...]
+// included = [{ type: 'wheels', id: '10', ... }, ...]
+```
+
+### Custom attributes
+
+Override `attributes()` to transform or compute attributes.
+
+```typescript
+class EventPresenter extends Presenter {
+  static type = 'events'
+  attributes(instance) {
+    const attrs = super.attributes(instance)
+    return { ...attrs, slug: attrs.name.toLowerCase().replace(/ /g, '-') }
+  }
+}
+```
+
+### Links
+
+Override `selfLinks()` for resource links and `links()` for relationship links.
+
+```typescript
+class CarPresenter extends Presenter {
+  static type = 'cars'
+  relationships() {
+    return { motor: MotorPresenter }
+  }
+  selfLinks(instance) {
+    return '/cars/' + this.id(instance)
+  }
+  links(instance) {
+    return {
+      motor: {
+        self: this.selfLinks(instance) + '/relationships/motor',
+        related: this.selfLinks(instance) + '/motor',
+      },
+    }
+  }
+}
+```
+
+### Render options
+
+Pass `meta` and `links` as top-level document properties:
+
+```typescript
+ItemPresenter.render(items, {
+  meta: { total: 100, page: 1 },
+  links: { self: '/items?page=1', next: '/items?page=2' },
+})
+```
+
+Rendering `null` produces `{ data: null }`. Arrays produce `{ data: [...] }`.
+
+## Store (Standard)
+
+Parses JSON API documents, resolves relationships, and caches models.
+
+```typescript
+const store = new Store()
+```
+
+### Syncing data
+
+```typescript
+// sync: returns model for single resource, array for collection
+const event = store.sync({ data: { type: 'events', id: '1', attributes: { name: 'Demo' } } })
+
+// syncAll: always returns array
+const events = store.syncAll(jsonApiDocument)
+
+// retrieve: returns single model or null (type-filtered)
+const event = store.retrieve('events', jsonApiDocument)
+
+// retrieveAll: always returns array, filtered by type
+const images = store.retrieveAll('images', jsonApiDocument)
+```
+
+### Querying cached data
+
+```typescript
+store.find('events', 1) // single model or null
+store.findAll('events') // all cached events
+store.remove('events', 1) // remove one
+store.remove('events') // remove all of type
+store.reset() // clear everything
+```
+
+### Relationships resolve automatically
+
+```typescript
+store.sync({
+  data: { type: 'events', id: '1', relationships: { images: { data: [{ type: 'images', id: '2' }] } } },
+  included: [{ type: 'images', id: '2', attributes: { url: 'pic.jpg' } }],
+})
+const event = store.find('events', '1')
+event.images[0].url // 'pic.jpg'
+```
+
+### Schema validation
+
+Accepts any Zod-like schema (must have `parse`/`safeParse` methods). Use `.passthrough()` on Zod objects so extra attributes aren't stripped.
+
+```typescript
+import { z } from 'zod'
+
+const eventSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+  })
+  .passthrough()
+
+const store = new Store({
+  schemas: { events: eventSchema },
+  strict: true, // throws on validation error; false collects in store.validationErrors
+})
+```
+
+### Accessing metadata via symbols
+
+```typescript
+import { getType, getMeta, getLinks, getRelationshipLinks, getRelationshipMeta } from 'yayson/utils'
+
+const event = store.find('events', '1')
+getType(event) // 'events'
+getMeta(event) // resource meta
+getLinks(event) // resource links
+getRelationshipLinks(event.images) // relationship links
+getRelationshipMeta(event.images) // relationship meta
+```
+
+## Store (Legacy)
+
+For pre-JSON API 1.0 flat format. Import from `yayson/legacy`.
+
+```typescript
+import yayson from 'yayson/legacy'
+const { Store } = yayson()
+
+const store = new Store({
+  types: { events: 'event', images: 'image' }, // plural -> singular mapping
+})
+```
+
+### Legacy data format
+
+```typescript
+store.sync({
+  links: {
+    'event.images': { type: 'images' },
+    'images.event': { type: 'event' },
+  },
+  event: { id: 1, name: 'Demo', images: [2] },
+  images: [{ id: 2, event: 1, url: 'pic.jpg' }],
+})
+
+const event = store.find('event', 1)
+event.images[0].url // 'pic.jpg'
+```
+
+The API methods (`sync`, `syncAll`, `retrieve`, `retrieveAll`, `find`, `findAll`, `remove`, `reset`) work the same as the standard Store. Schema validation is also supported.
+
+## Quick Reference
+
+For detailed API reference including all method signatures, return types, and edge cases, see [references/api.md](references/api.md).

package/skill/yayson/references/api.md

@@ -0,0 +1,266 @@
+# YAYSON API Reference
+
+## Table of Contents
+
+- [Factory Function](#factory-function)
+- [Presenter](#presenter)
+- [Store (Standard)](#store-standard)
+- [Store (Legacy)](#store-legacy)
+- [Symbols & Utilities](#symbols--utilities)
+- [Adapters](#adapters)
+- [Type Inference](#type-inference)
+
+## Factory Function
+
+```typescript
+import yayson from 'yayson'
+// or: import yayson from 'yayson/legacy'
+
+function yayson(options?: { adapter?: 'default' | 'sequelize' | AdapterClass }): {
+  Presenter: typeof Presenter
+  Store: typeof Store
+  Adapter: typeof Adapter
+}
+```
+
+## Presenter
+
+### Static Properties
+
+| Property  | Type             | Default     | Description                           |
+| --------- | ---------------- | ----------- | ------------------------------------- |
+| `type`    | `string`         | `'objects'` | JSON API resource type name           |
+| `fields`  | `string[]`       | `undefined` | Attribute whitelist (undefined = all) |
+| `adapter` | `typeof Adapter` | injected    | Data access adapter                   |
+
+### Instance Methods
+
+#### `relationships(): Record<string, typeof Presenter>`
+
+Return map of property names to their Presenter classes. Relationship keys are automatically excluded from attributes.
+
+```typescript
+relationships() {
+  return { author: AuthorPresenter, comments: CommentPresenter }
+}
+```
+
+#### `attributes(instance): Record<string, unknown>`
+
+Return attributes for the resource. Default strips `id` and relationship keys, then applies `fields` filter. Override to customize.
+
+#### `selfLinks(instance): string | { self: string, related?: string } | undefined`
+
+Return links for the resource itself. String is normalized to `{ self: string }`.
+
+#### `links(instance): Record<string, { self: string, related?: string }> | undefined`
+
+Return links keyed by relationship name. Applied to each relationship in the output.
+
+#### `id(instance): string | undefined`
+
+Extract ID via adapter. Returns stringified ID.
+
+### Static Methods
+
+#### `render(instanceOrCollection, options?): JsonApiDocument`
+
+#### `toJSON(instanceOrCollection, options?): JsonApiDocument`
+
+Serialize one or many instances to a JSON API document. `render` and `toJSON` are identical.
+
+**Options:**
+
+| Option  | Type                      | Description                       |
+| ------- | ------------------------- | --------------------------------- |
+| `meta`  | `Record<string, unknown>` | Top-level `meta` in the document  |
+| `links` | `JsonApiLinks`            | Top-level `links` in the document |
+
+**Return value:** `{ data, included?, meta?, links? }`
+
+- Single instance: `data` is a resource object
+- Array: `data` is an array of resource objects
+- `null`/`undefined`: `data` is `null`
+- `included` only present when relationships exist, automatically deduplicated
+
+### Circular Relationships
+
+Presenters handle circular references. If `Car` has a `Motor` and `Motor` has a `Car`, the serializer tracks visited resources and avoids infinite recursion. Circular resources appear once in `included`.
+
+## Store (Standard)
+
+```typescript
+new Store<S extends SchemaRegistry>(options?: {
+  schemas?: S
+  strict?: boolean  // default: false
+})
+```
+
+### Methods
+
+#### `sync(body: JsonApiDocument): StoreModel | StoreModel[]`
+
+Sync a JSON API document. Returns a single model when `data` is a single resource, an array when `data` is an array.
+
+#### `syncAll(body: JsonApiDocument): StoreModel[]`
+
+Always returns an array. Processes `included` first, then `data`. Clears previous validation errors. On strict validation failure, rolls back store state.
+
+#### `retrieve<T>(type: T, body: JsonApiDocument): InferModelType<S, T> | null`
+
+Sync and return the first model matching `type`, or null.
+
+#### `retrieveAll<T>(type: T, body: JsonApiDocument): InferModelType<S, T>[]`
+
+Sync and return only models of specified type, preserving order from `data`.
+
+#### `find<T>(type: T, id: string | number): InferModelType<S, T> | null`
+
+Look up a previously synced model by type and ID. Accepts numeric or string ID.
+
+#### `findAll<T>(type: T): InferModelType<S, T>[]`
+
+Return all synced models of a given type.
+
+#### `remove(type: string, id?: string | number): void`
+
+Remove a specific model or all models of a type.
+
+#### `reset(): void`
+
+Clear all cached data and validation errors.
+
+### Properties
+
+| Property           | Type                | Description                                                       |
+| ------------------ | ------------------- | ----------------------------------------------------------------- |
+| `validationErrors` | `ValidationError[]` | Errors from non-strict validation. Each has `type`, `id`, `error` |
+
+### Validation Modes
+
+**strict: true** - Throws on first validation error. Store state rolls back (unchanged).
+
+**strict: false** (default) - Collects errors in `store.validationErrors`. Models are still created. Each error contains:
+
+```typescript
+{ type: string, id: string, error: ZodError | Error }
+```
+
+### ID Handling
+
+- IDs are stored and matched as strings internally
+- Numeric IDs in source data are preserved on the model (e.g. `event.id` stays `1` not `'1'`)
+- `find('events', 1)` and `find('events', '1')` both work
+- Numeric IDs are preserved through relationship resolution
+
+### Duplicate Handling
+
+When the same resource (same type + id) appears multiple times, the store deduplicates by keeping one copy.
+
+## Store (Legacy)
+
+```typescript
+new LegacyStore<S extends SchemaRegistry>(options?: {
+  types?: Record<string, string>  // plural -> singular type mapping
+  schemas?: S
+  strict?: boolean
+})
+```
+
+### Key Differences from Standard Store
+
+1. **Data format**: Flat objects keyed by type name, not JSON API envelope
+2. **Type mapping**: `types` option maps plural keys to singular type names
+3. **Relationship links**: Defined in a `links` object within the data
+
+### Legacy Data Structure
+
+```typescript
+{
+  links: {
+    'event.images': { type: 'images' },
+    'images.event': { type: 'event' }
+  },
+  event: { id: 1, name: 'Demo', images: [2] },       // single
+  images: [{ id: 2, event: 1, url: 'pic.jpg' }]       // array
+}
+```
+
+### Methods
+
+Same as standard Store: `sync`, `syncAll`, `retrieve`, `retrieveAll`, `find`, `findAll`, `remove`, `reset`.
+
+Note: `find`/`findAll` use the **singular** (mapped) type name, not the plural key.
+
+## Symbols & Utilities
+
+Import from `yayson/utils`:
+
+```typescript
+import { TYPE, LINKS, META, REL_LINKS, REL_META } from 'yayson/utils'
+import { getType, getLinks, getMeta, getRelationshipLinks, getRelationshipMeta } from 'yayson/utils'
+```
+
+| Symbol      | Helper                      | Stored On          | Contains             |
+| ----------- | --------------------------- | ------------------ | -------------------- |
+| `TYPE`      | `getType(model)`            | Any model          | Resource type string |
+| `META`      | `getMeta(model)`            | Any model          | Resource-level meta  |
+| `LINKS`     | `getLinks(model)`           | Any model          | Resource-level links |
+| `REL_LINKS` | `getRelationshipLinks(rel)` | Relationship value | Relationship links   |
+| `REL_META`  | `getRelationshipMeta(rel)`  | Relationship value | Relationship meta    |
+
+Symbols survive schema validation (explicitly copied after `parse()`).
+
+## Adapters
+
+### Default Adapter
+
+Works with plain JS objects.
+
+```typescript
+Adapter.get(model) // returns shallow copy of all properties
+Adapter.get(model, 'key') // returns single property value
+Adapter.id(model) // returns model.id as string
+```
+
+### Sequelize Adapter
+
+Works with Sequelize model instances by calling `model.get()`.
+
+```typescript
+const { Presenter } = yayson({ adapter: 'sequelize' })
+```
+
+### Custom Adapter
+
+Any object with static `id(model)` and `get(model, key?)` methods:
+
+```typescript
+const { Presenter } = yayson({
+  adapter: {
+    id: (model) => String(model.pk),
+    get: (model, key) => (key ? model.attrs[key] : model.attrs),
+  },
+})
+```
+
+## Type Inference
+
+With schema registry, store methods infer TypeScript types automatically:
+
+```typescript
+const schemas = {
+  events: z.object({ id: z.string(), name: z.string() }).passthrough(),
+  images: z.object({ id: z.string(), url: z.string() }).passthrough(),
+} as const
+
+const store = new Store({ schemas })
+
+const event = store.find('events', '1')
+// TypeScript infers: { id: string, name: string, [key: string]: unknown } | null
+
+const images = store.findAll('images')
+// TypeScript infers: { id: string, url: string, [key: string]: unknown }[]
+```
+
+The `as const` on the schemas object is required for type inference to work.

package/.eslintrc.json

@@ -1,28 +0,0 @@
-{
-  "env": {
-    "commonjs": true,
-    "es6": true,
-    "mocha": true,
-    "node": true
-  },
-  "parser": "@babel/eslint-parser",
-  "parserOptions": {
-    "ecmaVersion": 2020
-  },
-  "ignorePatterns": ["node_modules", "dist"],
-  "rules": {
-    "eqeqeq": ["error", "smart"],
-    "semi": ["error", "never", { "beforeStatementContinuationChars": "always" }],
-    "no-extra-semi": "off"
-  },
-  "plugins": ["mocha"],
-  "extends": ["eslint:recommended", "plugin:mocha/recommended"],
-  "overrides": [
-    {
-      "files": ["test/**/*.js"],
-      "rules": {
-        "no-unused-vars": "off"
-      }
-    }
-  ]
-}

package/.github/workflows/node.js.yml

@@ -1,30 +0,0 @@
-# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
-name: Node.js CI
-
-on:
-  push:
-    branches: [ master ]
-  pull_request:
-    branches: [ master ]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [14.x, 16.x, 18.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
-
-    steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v2
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: npm ci
-    - run: npm run build --if-present
-    - run: npm test

package/.mocharc.js

@@ -1,15 +0,0 @@
-'use strict'
-
-module.exports = {
-  recursive: true,
-  require: ['test/node.js'],
-  diff: true,
-  extension: ['js'],
-  package: './package.json',
-  reporter: 'spec',
-  slow: 75,
-  timeout: 10000,
-  ui: 'bdd',
-  spec: ['test/yayson/**/*.js'],
-  'watch-files': ['src/**/*.js', 'test/**/*.js'],
-}

package/.nvmrc

@@ -1 +0,0 @@
-v18.13.0

package/RELEASE.md

@@ -1,3 +0,0 @@
-# Release process
-
-Should be just a single command with `npm run release`

package/babel.config.json

@@ -1,4 +0,0 @@
-{
-  "presets": [],
-  "plugins": []
-}

package/legacy.js

@@ -1,2 +0,0 @@
-const yayson = require('./src/legacy')
-module.exports = yayson

package/prettier.config.js

@@ -1,5 +0,0 @@
-module.exports = {
-  semi: false,
-  singleQuote: true,
-  printWidth: 120,
-}

package/src/legacy.js

@@ -1,14 +0,0 @@
-const yayson = require('./yayson')
-const legacyPresenter = require('./yayson/legacy-presenter')
-const legacyStore = require('./yayson/legacy-store')
-
-module.exports = function (options = {}) {
-  const { Store, Presenter, Adapter } = yayson(options)
-  return {
-    Store: legacyStore(Store),
-    Presenter: legacyPresenter(Presenter),
-    Adapter,
-  }
-}
-
-

package/src/yayson/adapter.js

@@ -1,18 +0,0 @@
-class Adapter {
-  static get(model, key) {
-    if (key) {
-      return model[key]
-    }
-    return model
-  }
-
-  static id(model) {
-    const id = this.get(model, 'id')
-    if (id === undefined) {
-      return id
-    }
-    return `${id}`
-  }
-}
-
-module.exports = Adapter

package/src/yayson/adapters/index.js

@@ -1 +0,0 @@
-module.exports = { sequelize: require('./sequelize') }

package/src/yayson/adapters/sequelize.js

@@ -1,11 +0,0 @@
-const Adapter = require('../adapter')
-
-class SequelizeAdapter extends Adapter {
-  static get(model, key) {
-    if (model != null) {
-      return model.get(key)
-    }
-  }
-}
-
-module.exports = SequelizeAdapter