json-rest-api 1.0.29 → 2.1.0

package/docs/GUIDE/GUIDE_X_Writing_Plugins.md

@@ -1,201 +0,0 @@
-# Writing Plugins
-
-`json-rest-api` is built as a set of plugins on top of `hooked-api`. This guide covers the public extension surface for plugin authors.
-
-Use this guide when you want to:
-
-- add resource-level behavior across many resources
-- add new scope methods
-- compile resource metadata into reusable runtime state
-- hook into query or write processing
-
-For internal architecture notes and maintainer-oriented details, see [docs/ONBOARDING.md](../ONBOARDING.md).
-
-## Minimal plugin shape
-
-```javascript
-export const MyPlugin = {
-  name: 'my-plugin',
-  dependencies: ['rest-api'],
-
-  install ({ addHook, addScopeMethod, helpers, log, pluginOptions = {} }) {
-    addHook('scope:added', 'compile-my-plugin', {}, ({ context, scopes }) => {
-      const scope = scopes[context.scopeName]
-      scope.vars.myPlugin = { enabled: true }
-    })
-
-    addScopeMethod('doSomething', async ({ scopeName, scope, params, context }) => {
-      return { scopeName, enabled: scope.vars.myPlugin?.enabled === true }
-    })
-  }
-}
-```
-
-The usual pattern is:
-
-1. compile resource metadata during `scope:added`
-2. store normalized state in `scope.vars`
-3. use hooks or scope methods to apply behavior at runtime
-
-## The stable extension points
-
-### `scope:added`
-
-Use this to inspect `scopeOptions`, validate configuration, and compile resource-specific runtime state into `scope.vars`.
-
-Typical uses:
-
-- compile autofilter presets
-- compile query-field definitions
-- validate resource-specific options
-
-Example:
-
-```javascript
-addHook('scope:added', 'compile-example', {}, ({ context, scopes }) => {
-  const scope = scopes[context.scopeName]
-  const options = scope.scopeOptions || {}
-
-  scope.vars.example = {
-    flag: options.exampleFlag === true
-  }
-})
-```
-
-### `beforeSchemaValidate`
-
-Use this to normalize or strip write input before schema validation runs.
-
-Typical uses:
-
-- inject derived input values
-- remove output-only fields from `POST`/`PUT`/`PATCH`
-- translate alternate request forms into canonical attributes/relationships
-
-Example:
-
-```javascript
-addHook('beforeSchemaValidate', 'strip-output-only-input', {}, ({ context }) => {
-  const attributes = context.inputRecord?.data?.attributes
-  if (!attributes) return
-
-  delete attributes.output_only_field
-})
-```
-
-### `knexQueryFiltering`
-
-Use this to add query constraints to the generated Knex query.
-
-Typical uses:
-
-- automatic scoping
-- cross-table filters
-- custom public filter semantics
-
-Example:
-
-```javascript
-addHook('knexQueryFiltering', 'scope-by-workspace', {}, async ({ context }) => {
-  const query = context.knexQuery?.query
-  if (!query) return
-
-  query.where('workspace_id', context.session.workspaceId)
-})
-```
-
-`knexQueryFiltering` is the right seam for filtering. It is **not** the right seam for turning ad hoc SQL aliases into first-class fields.
-
-For mandatory resource visibility, prefer the supported [`RowPolicyPlugin`](GUIDE_X_Row_Policies.md) contract over registering a raw filtering hook. It validates resource configuration, requires an explicit allow/deny decision, provides logical field translation, exposes query-purpose metadata, and is exercised across pagination counts, single-record preflights, includes, and relationship loading.
-
-### `addScopeMethod`
-
-Use this when a plugin needs a reusable method on every resource or selected resources.
-
-Example:
-
-```javascript
-addScopeMethod('introspect', async ({ vars }) => {
-  return {
-    tableName: vars.schemaInfo?.tableName,
-    fields: Object.keys(vars.schemaInfo?.schemaStructure || {})
-  }
-})
-```
-
-## The query-field seam
-
-`json-rest-api` now supports a small, explicit seam for **query-only read fields**.
-
-This is the seam used by `QueryProjectionsPlugin`, and it is the recommended pattern for plugins that need derived SQL-backed fields.
-
-### What a plugin should provide
-
-Compile resource-level definitions into:
-
-```javascript
-scope.vars.queryFields = {
-  full_name: {
-    type: 'string',
-    sortable: true,
-    hidden: false,
-    normallyHidden: false,
-    select: ({ knex, db, context, scopeName, tableName, fieldName, schemaInfo, adapter, column, ref }) => {
-      return knex.raw(
-        "trim(coalesce(??, '') || ' ' || coalesce(??, ''))",
-        [column('first_name'), column('last_name')]
-      )
-    }
-  }
-}
-```
-
-### What core will do with `scope.vars.queryFields`
-
-Once a plugin sets `scope.vars.queryFields`, core will:
-
-- include visible query fields by default in `get()` and `query()`
-- allow them in sparse fieldsets
-- allow them in sorting when the plugin marks them sortable
-- use them in cursor pagination with a stable `id` tie-breaker
-- carry them through included-resource selection
-- only expose declared query-field aliases on the AnyAPI path
-
-### What this seam is for
-
-Use it for:
-
-- SQL-backed projections
-- aggregate list fields
-- joined display labels
-- derived fields that must participate in `ORDER BY`
-
-Do **not** use it for:
-
-- writable fields
-- storage/schema ownership
-- migrations or introspection
-- normal response-only computed fields
-
-For the concrete projection example, see [Query Projections](GUIDE_X_Query_Projections.md).
-
-## Recommended plugin pattern
-
-When you add a new plugin feature, prefer this flow:
-
-1. read plugin options at install time
-2. validate and compile per-resource config in `scope:added`
-3. store only normalized runtime state in `scope.vars`
-4. use hooks or scope methods to apply behavior
-
-That keeps the plugin declarative and avoids re-parsing configuration during requests.
-
-## Boundaries to keep clean
-
-- Keep **query-layer** extensions out of `schema`.
-- Keep **write/input** reshaping in `beforeSchemaValidate`.
-- Keep **filtering** in `knexQueryFiltering`.
-- Keep **response-only** enrichment in `enrichAttributes`.
-- Do not rely on arbitrary internal helper filenames as public API.
-
-If a feature requires deeper integration than the public seams provide, treat that as a core extension discussion rather than a plugin hack.

package/docs/Gemfile

@@ -1,6 +0,0 @@
-source "https://rubygems.org"
-
-gem "github-pages", group: :jekyll_plugins
-gem "jekyll-relative-links"
-gem "jekyll-seo-tag"
-gem "webrick", "~> 1.9"

package/docs/Gemfile.lock

@@ -1,308 +0,0 @@
-GEM
-  remote: https://rubygems.org/
-  specs:
-    activesupport (8.0.2)
-      base64
-      benchmark (>= 0.3)
-      bigdecimal
-      concurrent-ruby (~> 1.0, >= 1.3.1)
-      connection_pool (>= 2.2.5)
-      drb
-      i18n (>= 1.6, < 2)
-      logger (>= 1.4.2)
-      minitest (>= 5.1)
-      securerandom (>= 0.3)
-      tzinfo (~> 2.0, >= 2.0.5)
-      uri (>= 0.13.1)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
-    base64 (0.2.0)
-    benchmark (0.4.1)
-    bigdecimal (3.2.2)
-    coffee-script (2.4.1)
-      coffee-script-source
-      execjs
-    coffee-script-source (1.12.2)
-    colorator (1.1.0)
-    commonmarker (0.23.11)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.3)
-    dnsruby (1.72.4)
-      base64 (~> 0.2.0)
-      logger (~> 1.6.5)
-      simpleidn (~> 0.2.1)
-    drb (2.2.3)
-    em-websocket (0.5.3)
-      eventmachine (>= 0.12.9)
-      http_parser.rb (~> 0)
-    ethon (0.16.0)
-      ffi (>= 1.15.0)
-    eventmachine (1.2.7)
-    execjs (2.10.0)
-    faraday (2.13.1)
-      faraday-net_http (>= 2.0, < 3.5)
-      json
-      logger
-    faraday-net_http (3.4.1)
-      net-http (>= 0.5.0)
-    ffi (1.17.2-aarch64-linux-gnu)
-    ffi (1.17.2-aarch64-linux-musl)
-    ffi (1.17.2-arm-linux-gnu)
-    ffi (1.17.2-arm-linux-musl)
-    ffi (1.17.2-arm64-darwin)
-    ffi (1.17.2-x86_64-darwin)
-    ffi (1.17.2-x86_64-linux-gnu)
-    ffi (1.17.2-x86_64-linux-musl)
-    forwardable-extended (2.6.0)
-    gemoji (4.1.0)
-    github-pages (230)
-      github-pages-health-check (= 1.18.2)
-      jekyll (= 3.9.5)
-      jekyll-avatar (= 0.8.0)
-      jekyll-coffeescript (= 1.2.2)
-      jekyll-commonmark-ghpages (= 0.4.0)
-      jekyll-default-layout (= 0.1.5)
-      jekyll-feed (= 0.17.0)
-      jekyll-gist (= 1.5.0)
-      jekyll-github-metadata (= 2.16.1)
-      jekyll-include-cache (= 0.2.1)
-      jekyll-mentions (= 1.6.0)
-      jekyll-optional-front-matter (= 0.3.2)
-      jekyll-paginate (= 1.1.0)
-      jekyll-readme-index (= 0.3.0)
-      jekyll-redirect-from (= 0.16.0)
-      jekyll-relative-links (= 0.7.0)
-      jekyll-remote-theme (= 0.4.3)
-      jekyll-sass-converter (= 1.5.2)
-      jekyll-seo-tag (= 2.8.0)
-      jekyll-sitemap (= 1.4.0)
-      jekyll-swiss (= 1.0.0)
-      jekyll-theme-architect (= 0.2.0)
-      jekyll-theme-cayman (= 0.2.0)
-      jekyll-theme-dinky (= 0.2.0)
-      jekyll-theme-hacker (= 0.2.0)
-      jekyll-theme-leap-day (= 0.2.0)
-      jekyll-theme-merlot (= 0.2.0)
-      jekyll-theme-midnight (= 0.2.0)
-      jekyll-theme-minimal (= 0.2.0)
-      jekyll-theme-modernist (= 0.2.0)
-      jekyll-theme-primer (= 0.6.0)
-      jekyll-theme-slate (= 0.2.0)
-      jekyll-theme-tactile (= 0.2.0)
-      jekyll-theme-time-machine (= 0.2.0)
-      jekyll-titles-from-headings (= 0.5.3)
-      jemoji (= 0.13.0)
-      kramdown (= 2.4.0)
-      kramdown-parser-gfm (= 1.1.0)
-      liquid (= 4.0.4)
-      mercenary (~> 0.3)
-      minima (= 2.5.1)
-      nokogiri (>= 1.13.6, < 2.0)
-      rouge (= 3.30.0)
-      terminal-table (~> 1.4)
-    github-pages-health-check (1.18.2)
-      addressable (~> 2.3)
-      dnsruby (~> 1.60)
-      octokit (>= 4, < 8)
-      public_suffix (>= 3.0, < 6.0)
-      typhoeus (~> 1.3)
-    html-pipeline (2.14.3)
-      activesupport (>= 2)
-      nokogiri (>= 1.4)
-    http_parser.rb (0.8.0)
-    i18n (1.14.7)
-      concurrent-ruby (~> 1.0)
-    jekyll (3.9.5)
-      addressable (~> 2.4)
-      colorator (~> 1.0)
-      em-websocket (~> 0.5)
-      i18n (>= 0.7, < 2)
-      jekyll-sass-converter (~> 1.0)
-      jekyll-watch (~> 2.0)
-      kramdown (>= 1.17, < 3)
-      liquid (~> 4.0)
-      mercenary (~> 0.3.3)
-      pathutil (~> 0.9)
-      rouge (>= 1.7, < 4)
-      safe_yaml (~> 1.0)
-    jekyll-avatar (0.8.0)
-      jekyll (>= 3.0, < 5.0)
-    jekyll-coffeescript (1.2.2)
-      coffee-script (~> 2.2)
-      coffee-script-source (~> 1.12)
-    jekyll-commonmark (1.4.0)
-      commonmarker (~> 0.22)
-    jekyll-commonmark-ghpages (0.4.0)
-      commonmarker (~> 0.23.7)
-      jekyll (~> 3.9.0)
-      jekyll-commonmark (~> 1.4.0)
-      rouge (>= 2.0, < 5.0)
-    jekyll-default-layout (0.1.5)
-      jekyll (>= 3.0, < 5.0)
-    jekyll-feed (0.17.0)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-gist (1.5.0)
-      octokit (~> 4.2)
-    jekyll-github-metadata (2.16.1)
-      jekyll (>= 3.4, < 5.0)
-      octokit (>= 4, < 7, != 4.4.0)
-    jekyll-include-cache (0.2.1)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-mentions (1.6.0)
-      html-pipeline (~> 2.3)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-optional-front-matter (0.3.2)
-      jekyll (>= 3.0, < 5.0)
-    jekyll-paginate (1.1.0)
-    jekyll-readme-index (0.3.0)
-      jekyll (>= 3.0, < 5.0)
-    jekyll-redirect-from (0.16.0)
-      jekyll (>= 3.3, < 5.0)
-    jekyll-relative-links (0.7.0)
-      jekyll (>= 3.3, < 5.0)
-    jekyll-remote-theme (0.4.3)
-      addressable (~> 2.0)
-      jekyll (>= 3.5, < 5.0)
-      jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
-      rubyzip (>= 1.3.0, < 3.0)
-    jekyll-sass-converter (1.5.2)
-      sass (~> 3.4)
-    jekyll-seo-tag (2.8.0)
-      jekyll (>= 3.8, < 5.0)
-    jekyll-sitemap (1.4.0)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-swiss (1.0.0)
-    jekyll-theme-architect (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-cayman (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-dinky (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-hacker (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-leap-day (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-merlot (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-midnight (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-minimal (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-modernist (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-primer (0.6.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-github-metadata (~> 2.9)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-slate (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-tactile (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-time-machine (0.2.0)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-titles-from-headings (0.5.3)
-      jekyll (>= 3.3, < 5.0)
-    jekyll-watch (2.2.1)
-      listen (~> 3.0)
-    jemoji (0.13.0)
-      gemoji (>= 3, < 5)
-      html-pipeline (~> 2.2)
-      jekyll (>= 3.0, < 5.0)
-    json (2.12.2)
-    kramdown (2.4.0)
-      rexml
-    kramdown-parser-gfm (1.1.0)
-      kramdown (~> 2.0)
-    liquid (4.0.4)
-    listen (3.9.0)
-      rb-fsevent (~> 0.10, >= 0.10.3)
-      rb-inotify (~> 0.9, >= 0.9.10)
-    logger (1.6.6)
-    mercenary (0.3.6)
-    minima (2.5.1)
-      jekyll (>= 3.5, < 5.0)
-      jekyll-feed (~> 0.9)
-      jekyll-seo-tag (~> 2.1)
-    minitest (5.25.5)
-    net-http (0.6.0)
-      uri
-    nokogiri (1.18.8-aarch64-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.18.8-aarch64-linux-musl)
-      racc (~> 1.4)
-    nokogiri (1.18.8-arm-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.18.8-arm-linux-musl)
-      racc (~> 1.4)
-    nokogiri (1.18.8-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-musl)
-      racc (~> 1.4)
-    octokit (4.25.1)
-      faraday (>= 1, < 3)
-      sawyer (~> 0.9)
-    pathutil (0.16.2)
-      forwardable-extended (~> 2.6)
-    public_suffix (5.1.1)
-    racc (1.8.1)
-    rb-fsevent (0.11.2)
-    rb-inotify (0.11.1)
-      ffi (~> 1.0)
-    rexml (3.4.1)
-    rouge (3.30.0)
-    rubyzip (2.4.1)
-    safe_yaml (1.0.5)
-    sass (3.7.4)
-      sass-listen (~> 4.0.0)
-    sass-listen (4.0.0)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-    sawyer (0.9.2)
-      addressable (>= 2.3.5)
-      faraday (>= 0.17.3, < 3)
-    securerandom (0.4.1)
-    simpleidn (0.2.3)
-    terminal-table (1.8.0)
-      unicode-display_width (~> 1.1, >= 1.1.1)
-    typhoeus (1.4.1)
-      ethon (>= 0.9.0)
-    tzinfo (2.0.6)
-      concurrent-ruby (~> 1.0)
-    unicode-display_width (1.8.0)
-    uri (1.0.3)
-    webrick (1.9.1)
-
-PLATFORMS
-  aarch64-linux-gnu
-  aarch64-linux-musl
-  arm-linux-gnu
-  arm-linux-musl
-  arm64-darwin
-  x86_64-darwin
-  x86_64-linux-gnu
-  x86_64-linux-musl
-
-DEPENDENCIES
-  github-pages
-  jekyll-relative-links
-  jekyll-seo-tag
-  webrick (~> 1.9)
-
-BUNDLED WITH
-   2.6.9