feat(evaluate): divide realms into core and contrib (#186)

BREAKING CHANGE: only json and map-set realms and still part of the package. apidom, minim and immutable are no longer part of npm distributions but live in contrib directory in the GitHub repo.

Closes #65
Closes #33

Author: char0n

CLAUDE.md

@@ -2,6 +2,14 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Environment Setup
+
+Before running any commands, ensure you're using the correct Node.js version specified in `.nvmrc`:
+
+```bash
+nvm use                  # Switch to Node.js version from .nvmrc
+```
+
 ## Build Commands
 
 ```bash
@@ -26,14 +34,17 @@ This is an RFC 6901 JSON Pointer implementation providing parsing, validation, e
 
 ### Evaluation Realms
 
-The realm system (`src/evaluate/realms/`) enables polymorphic evaluation across different data structures:
+The realm system enables polymorphic evaluation across different data structures.
 
+**Published realms** (`src/evaluate/realms/`):
 - `json/` - Default realm for plain JS objects/arrays
 - `map-set/` - Supports Map and Set instances
+- `compose.js` - Composes multiple realms (order matters: specific before generic)
+
+**Contrib realms** (`contrib/realms/`) - copy-paste examples, not published:
 - `minim/` - For minim element structures (API description tools)
 - `apidom/` - For ApiDOM structures (OpenAPI/AsyncAPI processing)
 - `immutable/` - For Immutable.js structures
-- `compose.js` - Composes multiple realms (order matters: specific before generic)
 
 Custom realms extend `EvaluationRealm` base class implementing: `isArray`, `isObject`, `sizeOf`, `has`, `evaluate`.
 

README.md

@@ -44,9 +44,6 @@
       - [Evaluation Realms](#evaluation-realms)
         - [JSON](#json-evaluation-realm)
         - [Map/Set](#mapset-evaluation-realm)
-        - [Minim](#minim-evaluation-realm)
-        - [ApiDOM](#apidom-evaluation-realm)
-        - [Immutable.js](#immutablejs-evaluation-realm)
         - [Custom](#custom-evaluation-realms)
         - [Composing Realms](#composing-evaluation-realms)
       - [Evaluation Diagnostics](#evaluation-diagnostics)
@@ -373,7 +370,7 @@ An **evaluation realm** defines the rules for interpreting and navigating data s
 While JSON Pointer traditionally operates on JSON objects and arrays, evaluation realms allow the evaluation to work
 polymorphically with different data structures, such as [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map),
 [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set), [Immutable.js](https://immutable-js.com/),
-or even custom representations like [ApiDOM](https://github.com/swagger-api/apidom).
+or even custom representations like [SpecLynx ApiDOM](https://github.com/speclynx/apidom).
 Realm can be specified via the `realm` option in the `evalute()` function.
 
 ###### JSON Evaluation Realm
@@ -418,93 +415,6 @@ const map = new Map([
 evaluate(map, '/a/1', { realm: new MapSetEvaluationRealm() }); // => 'c'
 ```
 
-###### Minim Evaluation Realm
-
-The Minim Evaluation Realm extends JSON Pointer evaluation to support `minim` data structures,
-specifically `ObjectElement`, `ArrayElement`, and other element types from the [minim](https://github.com/refractproject/minim).
-
-Minim is widely used in API description languages (e.g., OpenAPI, API Blueprint, AsyncAPI and other API Description processing tools)
-to represent structured API data. The Minim Evaluation Realm enables seamless JSON Pointer traversal for these structures.
-
-Before using the Minim Evaluation Realm, you need to install the `minim` package:
-
-```sh
- $ npm install --save minim
-```
-
-```js
-import { ObjectElement } from 'minim';
-import { evaluate } from '@swaggerexpert/json-pointer';
-import MinimEvaluationRealm from '@swaggerexpert/json-pointer/evaluate/realms/minim';
-
-const objectElement = new ObjectElement({
-  a: ['b', 'c']
-});
-
-evaluate(objectElement, '/a/1', { realm: new MinimEvaluationRealm() }); // => StringElement('c')
-```
-
-###### ApiDOM Evaluation Realm
-
-The [ApiDOM](https://github.com/swagger-api/apidom) Evaluation Realm is an integration layer that enables
-evaluation of JSON Pointer expressions on ApiDOM structures. It provides compatibility with ApiDOM [core](https://github.com/swagger-api/apidom/tree/main/packages/apidom-core) and namespace packages (`@swagger-api/apidom-ns-*`),
-allowing to traverse and query ApiDOM element instances.
-
-Before using the ApiDOM Evaluation Realm, you need to install the `@swagger-api/apidom-core` package:
-
-```sh
- $ npm install --save @swagger-api/apidom-core
-```
-
-```js
-import { ObjectElement } from '@swagger-api/apidom-core';
-import { evaluate } from '@swaggerexpert/json-pointer';
-import ApiDOMEvaluationRealm from '@swaggerexpert/json-pointer/evaluate/realms/apidom';
-
-const objectElement = new ObjectElement({
-  a: ['b', 'c']
-});
-
-evaluate(objectElement, '/a/1', { realm: new ApiDOMEvaluationRealm() }); // => StringElement('c')
-```
-
-or using contextual evaluation:
-
-```js
-import { ObjectElement } from '@swagger-api/apidom-core';
-import { evaluate } from '@swaggerexpert/json-pointer/evaluate/realms/apidom';
-
-const objectElement = new ObjectElement({
-  a: ['b', 'c']
-});
-
-evaluate(objectElement, '/a/1'); // => StringElement('c')
-```
-
-###### Immutable.js Evaluation Realm
-
-The [Immutable.js](https://immutable-js.com/) Evaluation Realm is an integration layer that enables
-evaluation of JSON Pointer expressions on Immutable.js structures.
-
-Before using the Immutable.js Evaluation Realm, you need to install the `immutable` package:
-
-```sh
- $ npm install --save immutable
-```
-
-```js
-import { fromJS } from 'immutable';
-import { evaluate } from '@swaggerexpert/json-pointer';
-import ImmutableEvaluationRealm from '@swaggerexpert/json-pointer/evaluate/realms/immutable';
-
-const map = fromJS({
-  a: ['b', 'c']
-});
-
-evaluate(map, '/a/1', { realm: new ImmutableEvaluationRealm() }); // => 'c'
-```
-
-
 ###### Custom Evaluation Realms
 
 The evaluation is designed to support **custom evaluation realms**,
@@ -530,6 +440,10 @@ class CustomEvaluationRealm extends EvaluationRealm {
 evaluate({ a: 'b' }, '/a', { realm: new CustomEvaluationRealm() }); // => 'b'
 ```
 
+Reference implementations for [Minim](https://github.com/refractproject/minim), [SpecLynx ApiDOM](https://github.com/speclynx/apidom),
+and [Immutable.js](https://immutable-js.com/) are available in the [`contrib/realms/`](https://github.com/swaggerexpert/json-pointer/tree/main/contrib/realms) directory.
+These can be copied and adapted for your specific needs.
+
 ###### Composing Evaluation Realms
 
 Evaluation realms can be composed to create complex evaluation scenarios,

contrib/realms/apidom/README.md

@@ -0,0 +1,34 @@
+# ApiDOM Evaluation Realm
+
+Evaluation realm for [SpecLynx ApiDOM](https://github.com/speclynx/apidom) structures, used for OpenAPI and AsyncAPI processing.
+
+## Requirements
+
+```bash
+npm install @speclynx/apidom-datamodel
+```
+
+## Usage
+
+```js
+import { evaluate } from '@swaggerexpert/json-pointer';
+import { ObjectElement } from '@speclynx/apidom-datamodel';
+import ApiDOMEvaluationRealm from './index.js';
+
+const element = new ObjectElement({
+  foo: ['bar', 'baz'],
+  '': 0,
+});
+
+const realm = new ApiDOMEvaluationRealm();
+
+evaluate(element, '/foo/0', { realm }); // => StringElement('bar')
+evaluate(element, '/', { realm }); // => NumberElement(0)
+```
+
+## Features
+
+- Supports `ObjectElement` and `ArrayElement` from ApiDOM
+- Validates array indices as unsigned 32-bit integers
+- Enforces unique member names in objects (as required by JSON Pointer spec)
+- Works with refracted OpenAPI/AsyncAPI documents

src/evaluate/realms/apidom/realm.js contrib/realms/apidom/index.jssrc/evaluate/realms/apidom/realm.js renamed to contrib/realms/apidom/index.js

@@ -1,8 +1,6 @@
-import { isObjectElement, isArrayElement } from '@swagger-api/apidom-core';
+import { isObjectElement, isArrayElement } from '@speclynx/apidom-datamodel';
 
-import EvaluationRealm from '../EvaluationRealm.js';
-import JSONPointerKeyError from '../../../errors/JSONPointerKeyError.js';
-import JSONPointerIndexError from '../../../errors/JSONPointerIndexError.js';
+import { EvaluationRealm, JSONPointerKeyError, JSONPointerIndexError } from '@swaggerexpert/json-pointer';
 
 class ApiDOMEvaluationRealm extends EvaluationRealm {
   name = 'apidom';

contrib/realms/immutable/README.md

@@ -0,0 +1,33 @@
+# Immutable.js Evaluation Realm
+
+Evaluation realm for [Immutable.js](https://immutable-js.com/) data structures.
+
+## Requirements
+
+```bash
+npm install immutable
+```
+
+## Usage
+
+```js
+import { evaluate } from '@swaggerexpert/json-pointer';
+import { Map, List } from 'immutable';
+import ImmutableEvaluationRealm from './index.js';
+
+const structure = Map({
+  foo: List(['bar', 'baz']),
+  '': 0,
+});
+
+const realm = new ImmutableEvaluationRealm();
+
+evaluate(structure, '/foo/0', { realm }); // => 'bar'
+evaluate(structure, '/', { realm }); // => 0
+```
+
+## Features
+
+- Supports `Map` and `List` from Immutable.js
+- Seamless integration with immutable data structures
+- Can be composed with other realms for mixed data structures

src/evaluate/realms/immutable/index.js contrib/realms/immutable/index.jssrc/evaluate/realms/immutable/index.js renamed to contrib/realms/immutable/index.js

@@ -1,6 +1,6 @@
 import Immutable from 'immutable';
 
-import EvaluationRealm from '../EvaluationRealm.js';
+import { EvaluationRealm } from '@swaggerexpert/json-pointer';
 
 const { List, Map } = Immutable;
 

contrib/realms/minim/README.md

@@ -0,0 +1,33 @@
+# Minim Evaluation Realm
+
+Evaluation realm for [Minim](https://github.com/refractproject/minim) element structures, commonly used in API description tools.
+
+## Requirements
+
+```bash
+npm install minim
+```
+
+## Usage
+
+```js
+import { evaluate } from '@swaggerexpert/json-pointer';
+import { ObjectElement } from 'minim';
+import MinimEvaluationRealm from './index.js';
+
+const element = new ObjectElement({
+  foo: ['bar', 'baz'],
+  '': 0,
+});
+
+const realm = new MinimEvaluationRealm();
+
+evaluate(element, '/foo/0', { realm }); // => StringElement('bar')
+evaluate(element, '/', { realm }); // => NumberElement(0)
+```
+
+## Features
+
+- Supports `ObjectElement` and `ArrayElement` from minim
+- Validates array indices as unsigned 32-bit integers
+- Enforces unique member names in objects (as required by JSON Pointer spec)

src/evaluate/realms/minim/index.js contrib/realms/minim/index.jssrc/evaluate/realms/minim/index.js renamed to contrib/realms/minim/index.js

@@ -1,8 +1,6 @@
 import { ObjectElement, ArrayElement } from 'minim';
 
-import EvaluationRealm from '../EvaluationRealm.js';
-import JSONPointerKeyError from '../../../errors/JSONPointerKeyError.js';
-import JSONPointerIndexError from '../../../errors/JSONPointerIndexError.js';
+import { EvaluationRealm, JSONPointerKeyError, JSONPointerIndexError } from '@swaggerexpert/json-pointer';
 
 class MinimEvaluationRealm extends EvaluationRealm {
   name = 'minim';