@shipworthy/openapi-parser 0.0.1 → 0.0.2

package/README.md

@@ -4,6 +4,10 @@ Load an OpenAPI 3.0 or 3.1 document from a file path, a URL, a JSON or YAML stri
 
 The API is Effect-native. Every entry point is an `Effect` or an Effect `Schema` codec, so you need [`effect`](https://www.npmjs.com/package/effect) v4 to run it.
 
+Bundling preserves OpenAPI 3.1 schema keywords alongside `$ref`, including descriptions,
+constraints, and extensions. It rewrites external references to internal references without
+introducing `allOf` wrappers for their sibling keywords.
+
 ## Installation
 
 ```sh
@@ -14,10 +18,9 @@ bun add @shipworthy/openapi-parser effect @effect/platform-node
 
 | Requirement   | Details                                                                                                                                                                                                                                                                                                                                           |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `effect`      | `^4.0.0`, a peer dependency. Install it yourself so your application and the parser share one copy to run the returned effects and to use the schemas.                                                                                                                                                                                            |
+| `effect`      | `^4.0.0`, a regular dependency. Add a compatible version to your own `package.json` so your application and the parser resolve to one copy to run the returned effects and to use the schemas.                                                                                                                                                    |
 | Platform      | `@effect/platform-node` `^4.0.0` is a regular dependency. Install it yourself only if your code imports it, as the examples here do for `NodeServices`. The parser imports `node:stream`, `node:url`, `node:path`, `node:dns/promises`, `node:net`, and the `Buffer` global, so it needs Node.js `>=22.19.0` or Bun. It does not run in browsers. |
 | Module format | ESM only (`"type": "module"`). Ships compiled JavaScript with `.d.ts` declarations; no TypeScript loader or bundler is needed.                                                                                                                                                                                                                    |
-| Peer deps     | `effect` `^4.0.0`.                                                                                                                                                                                                                                                                                                                                |
 
 ## Quick start
 
@@ -354,7 +357,7 @@ None of these settings can be configured through the public API.
 - Load files with `URL` or `file://` strings. Bare strings are parsed as JSON or YAML text.
 - Input can be OpenAPI 3.0 or 3.1. Output is always bundled and upgraded OpenAPI 3.1 (`openapi: "3.1.0"` when upgraded from 3.0), with external refs moved into `components`.
 - Every error is a `Schema.SchemaError`. Read `error.message`.
-- Requires `effect` `^4.0.0` (peer dependency), ESM, and Node.js `>=22.19.0` or Bun. Ships compiled JavaScript. It does not run in browsers.
+- Depends on `effect` `^4.0.0`. ESM only, and Node.js `>=22.19.0` or Bun. Ships compiled JavaScript. It does not run in browsers.
 - Next step in the toolchain: pass the result to `decode` from `@shipworthy/openapi-transformer` to get a `ParsedService` for code generators.
 
 ## License

package/dist/pipeline.js

@@ -94,7 +94,7 @@ function normalizeSchema(value) {
     const record = asRecord(value);
     if (!record)
         throw bundleFailure("A schema position must contain an object or a boolean");
-    const normalized = JsonSchema.fromSchemaOpenApi3_1(liftSiblings(record));
+    const normalized = JsonSchema.fromSchemaOpenApi3_1(record);
     // A schema $id is its own resource, so its $defs join the shared pool.
     // Nested $defs on a schema without $id stay on that schema.
     if (typeof record.$id === "string")
@@ -156,31 +156,6 @@ function rewriteDefName(schema, from, to) {
     for (const value of Object.values(record))
         rewriteDefName(value, from, to);
 }
-function liftSiblings(value) {
-    if (Array.isArray(value))
-        return value.map((item) => liftSiblings(item));
-    const record = asRecord(value);
-    if (!record)
-        return value;
-    const lifted = {};
-    for (const [key, child] of Object.entries(record))
-        lifted[key] = liftSiblings(child);
-    if (typeof lifted.$ref !== "string")
-        return lifted;
-    const siblings = { ...lifted };
-    delete siblings.$ref;
-    // readOnly/writeOnly stay beside $ref so generators can wrap the reference itself.
-    const flags = {};
-    for (const key of ["readOnly", "writeOnly"]) {
-        if (siblings[key] === true) {
-            flags[key] = true;
-            delete siblings[key];
-        }
-    }
-    if (Object.keys(siblings).length === 0)
-        return { $ref: lifted.$ref, ...flags };
-    return { allOf: [{ $ref: lifted.$ref }, siblings], ...flags };
-}
 function recursiveNames(definitions) {
     const names = Object.keys(definitions);
     const dependencies = new Map(names.map((name) => [name, collectDefRefs(definitions[name])]));
@@ -246,30 +221,42 @@ function resolveValue(value, definitions, rootDefs, recursive, aliases, resolvin
         return value;
     if (typeof record.$ref === "string") {
         const key = referenceKey(record.$ref);
-        if (!key)
-            return record;
-        if (!Object.hasOwn(definitions, key)) {
+        if (key && !Object.hasOwn(definitions, key)) {
             if (rootDefs.has(key)) {
                 record.$ref = rootDefRef(key);
-                return record;
             }
-            throw missingPointerFailure(key, record.$ref, record.$ref);
+            else {
+                throw missingPointerFailure(key, record.$ref, record.$ref);
+            }
         }
-        const final = finalName(key, definitions, aliases);
-        const ref = joinPointer("#/$defs", final);
-        if (recursive.has(final) || mode === "bundle") {
-            if (recursive.has(final))
-                hooks?.onCircular?.(pointer);
-            record.$ref = ref;
-            return record;
+        else if (key) {
+            const final = finalName(key, definitions, aliases);
+            const ref = joinPointer("#/$defs", final);
+            if (recursive.has(final) || mode === "bundle") {
+                if (recursive.has(final))
+                    hooks?.onCircular?.(pointer);
+                record.$ref = ref;
+            }
+            else {
+                if (resolving.has(final))
+                    throw circularAliasFailure(final);
+                resolving.add(final);
+                const resolved = resolveValue(structuredClone(definitions[final]), definitions, rootDefs, recursive, aliases, resolving, mode, hooks, ref);
+                resolving.delete(final);
+                const siblings = { ...record };
+                delete siblings.$ref;
+                const result = Object.keys(siblings).length === 0
+                    ? resolved
+                    : {
+                        allOf: [
+                            resolved,
+                            resolveValue(siblings, definitions, rootDefs, recursive, aliases, resolving, mode, hooks, pointer),
+                        ],
+                    };
+                hooks?.onDereference?.(pointer, result, record, "$ref");
+                return result;
+            }
         }
-        if (resolving.has(final))
-            throw circularAliasFailure(final);
-        resolving.add(final);
-        const resolved = resolveValue(structuredClone(definitions[final]), definitions, rootDefs, recursive, aliases, resolving, mode, hooks, ref);
-        resolving.delete(final);
-        hooks?.onDereference?.(pointer, resolved, record, "$ref");
-        return resolved;
     }
     for (const [key, child] of Object.entries(record)) {
         record[key] = resolveValue(child, definitions, rootDefs, recursive, aliases, resolving, mode, hooks, joinPointer(pointer, key));

package/package.json

@@ -1,13 +1,11 @@
 {
   "name": "@shipworthy/openapi-parser",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@effect/platform-node": "^4.0.0"
-  },
-  "peerDependencies": {
+    "@effect/platform-node": "^4.0.0",
     "effect": "^4.0.0"
   },
   "description": "Parse, bundle, and upgrade OpenAPI documents with Effect schemas.",
@@ -37,7 +35,6 @@
     "@effect/vitest": "4.0.0",
     "@shipworthy/typescript-config": "0.0.1",
     "@types/node": "^24.10.3",
-    "effect": "^4.0.0",
     "typescript": "^7.0.2",
     "vitest": "5.0.3"
   },