@shipworthy/openapi-transformer 0.0.2 → 1.0.0

package/README.md

@@ -14,9 +14,9 @@ bun add @shipworthy/openapi-transformer @shipworthy/openapi-parser effect @effec
 
 Requirements:
 
-- **`effect` `^4.0.0`.** It is a dependency. `decode` returns an `Effect` and the model types are Effect `Schema`s, so add a compatible version to your app so both resolve to one copy of `effect` to run and compose them.
+- **`effect` `4.1.4`.** It is a dependency. `decode` returns an `Effect` and the model types are Effect `Schema`s, so add a compatible version to your app so both resolve to one copy of `effect` to run and compose them.
 - **`@shipworthy/openapi-parser`.** It is a dependency. You install it yourself to produce the input document, and its `bundleDocument` / `ParsedOpenApiFromString` are the usual entry points.
-- **`@effect/platform-node` `^4.0.0`** (or `@effect/platform-bun`), only because the quick start imports `NodeServices` to provide services to the parser. This package does not depend on it.
+- **`@effect/platform-node` `4.1.4`** (or `@effect/platform-bun`), only because the quick start imports `NodeServices` to provide services to the parser. This package does not depend on it.
 - **ESM only** (`"type": "module"`). There is no CommonJS build. The package ships compiled JavaScript with `.d.ts` declarations, so no TypeScript loader or bundler is needed.
 - **Node.js `>=22.19.0` or Bun.**
 
@@ -90,6 +90,8 @@ The package has a single entry point, `@shipworthy/openapi-transformer`. It expo
 | `ParsedService` and the other `Parsed*` names                              | `Schema` + type         | The model. See [Model](#model).                                        |
 | `HttpMethodName`, `ParamStyle`, `ParameterLocation`, `SecurityDeclaration` | `Schema` + literal type | Enumerations used in the model.                                        |
 | `httpMethods`, `parameterLocations`                                        | `readonly` tuple        | The lowercase method keys and the parameter locations, in model order. |
+| `propertyName`, `collidingProperties`, `schemaPropertyCollision`           | functions               | Shared field naming and collision checks for generators.               |
+| `camelCaseSchema`                                                          | function                | Rename snake_case property names throughout a schema tree.             |
 
 Each `Parsed*` name is exported both as a value (an Effect `Schema`) and as a type (`typeof X.Type`). Use `import type { ParsedOperation }` when you only need the type.
 
@@ -180,6 +182,20 @@ const check = Schema.toStandardSchemaV1(ParsedService);
 check["~standard"].validate(model); // { value } or { issues }
 ```
 
+### `camelCaseSchema(schema)`
+
+```ts
+const camelCaseSchema: (schema: ParsedSchema) => ParsedSchema;
+```
+
+Returns a copy of a schema tree in which lower snake_case property names become camelCase, using `propertyName(name, true)`. Names that are not lower snake_case, such as `already_Camel`, `_private`, `UPPER_CASE`, or `a`, are unchanged. The input is not modified, and booleans are returned as they are.
+
+- Renamed: keys of `properties` and `dependentSchemas`, string entries of `required`, keys and value entries of `dependentRequired`, and `discriminator.propertyName`. `discriminator.mapping` is unchanged.
+- Recursed into: `properties`, `patternProperties`, `dependentSchemas`, `$defs`, `additionalProperties`, `unevaluatedProperties`, `items`, `unevaluatedItems`, `contains`, `propertyNames`, `not`, `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, and `prefixItems`. A value that is not an object or a boolean is left as it is.
+- Unchanged: `patternProperties` keys, `$ref`, `enum`, `const`, `default`, `example`, `examples`, `x-*` extensions, and every other keyword.
+
+It does not resolve `$ref`s and does not detect collisions. Call `schemaPropertyCollision(schema, resolve)` first and fail on its result.
+
 ## Model
 
 These conventions apply across the whole model:
@@ -394,7 +410,7 @@ function requiresAuth(operation: ParsedOperation) {
 
 ## Key facts (for AI agents)
 
-- Import from `@shipworthy/openapi-transformer`. It has one entry point, is ESM-only, ships compiled JavaScript, depends on `effect` `^4.0.0`, and runs on Node.js `>=22.19.0` or Bun.
+- Import from `@shipworthy/openapi-transformer`. It has one entry point, is ESM-only, ships compiled JavaScript, depends on `effect` `4.1.4`, and runs on Node.js `>=22.19.0` or Bun.
 - Pipeline: `bundleDocument(source)` (from `@shipworthy/openapi-parser`, needs FileSystem/Path/HttpClient layers) → `decode(document)` → `ParsedService`.
 - `decode` is `Schema.decodeEffect(ParsedServiceFromParsedOpenApi)`. It returns `Effect<ParsedService, Schema.SchemaError>` and needs no services. Run it with `Effect.runSync` or `Effect.runPromise`.
 - Generators and plugins must type their input as `ParsedService` and walk it through the exported `Parsed*` types. Schema nodes are `ParsedSchema` (`JsonSchema | boolean`). Do not use a local `{ [key: string]: any }` stand-in.

package/dist/case.d.ts

@@ -0,0 +1,15 @@
+import { ParsedSchema } from "./model/schema.ts";
+export declare function propertyName(name: string, camelCase: boolean): string;
+export declare function collidingProperties(names: readonly string[], camelCase: boolean): readonly [string, string] | undefined;
+/** Find a name collision at any object depth reached through composition and references. */
+export declare function schemaPropertyCollision(schema: ParsedSchema, resolve: (ref: string) => ParsedSchema | undefined, extraNames?: readonly string[]): readonly [string, string] | undefined;
+/**
+ * Rename snake_case property names to camelCase throughout a schema tree.
+ *
+ * Renames `properties` keys, `required` entries, `dependentRequired` keys and values,
+ * `dependentSchemas` keys, and `discriminator.propertyName` with `propertyName(name, true)`, and
+ * recurses into every subschema. Values such as `enum`, `const`, `default`, and `examples`,
+ * `patternProperties` keys, and `$ref`s keep their spelling. References are not resolved and
+ * collisions are not detected; use `schemaPropertyCollision` first. The input is not modified.
+ */
+export declare function camelCaseSchema(schema: ParsedSchema): ParsedSchema;

package/dist/case.js

@@ -0,0 +1,153 @@
+import { Array, Predicate, Record, Schema, String } from "effect";
+import { ParsedSchema } from "./model/schema.js";
+const isParsedSchema = Schema.is(ParsedSchema);
+const snakeCase = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
+export function propertyName(name, camelCase) {
+    return camelCase && snakeCase.test(name) ? String.snakeToCamel(name) : name;
+}
+export function collidingProperties(names, camelCase) {
+    if (!camelCase)
+        return undefined;
+    const seen = new Map();
+    return Array.reduce(names, undefined, (collision, name) => {
+        if (collision)
+            return collision;
+        const transformed = propertyName(name, true);
+        const previous = seen.get(transformed);
+        seen.set(transformed, name);
+        return previous !== undefined && previous !== name ? [previous, name] : undefined;
+    });
+}
+function schemaEntries(value) {
+    return Predicate.isObject(value)
+        ? Array.filter(Record.toEntries(value), (entry) => isParsedSchema(entry[1]))
+        : [];
+}
+function schemaList(value) {
+    const candidates = Array.isArray(value) ? value : [];
+    return Array.filter(candidates, (candidate) => isParsedSchema(candidate));
+}
+/** Find a name collision at any object depth reached through composition and references. */
+export function schemaPropertyCollision(schema, resolve, extraNames = []) {
+    const schemaIds = new WeakMap();
+    const inspected = new Set();
+    let nextId = 0;
+    const expand = (current, visitedRefs) => {
+        if (!Predicate.isObject(current))
+            return [];
+        const ref = Predicate.isString(current.$ref) ? current.$ref : undefined;
+        const referenced = ref && !visitedRefs.has(ref) ? resolve(ref) : undefined;
+        const nextRefs = ref ? new Set(visitedRefs).add(ref) : visitedRefs;
+        const variants = Array.flatMap(["allOf", "anyOf", "oneOf"], (keyword) => schemaList(current[keyword]));
+        return [
+            current,
+            ...Array.flatMap(referenced === undefined ? variants : [referenced, ...variants], (member) => expand(member, nextRefs)),
+        ];
+    };
+    const inspect = (schemas, additionalNames = []) => {
+        const expanded = Array.flatMap(schemas, (member) => expand(member, new Set()));
+        if (expanded.length === 0)
+            return undefined;
+        const signature = Array.join(Array.map(expanded, (member) => {
+            let id = schemaIds.get(member);
+            if (id === undefined) {
+                id = ++nextId;
+                schemaIds.set(member, id);
+            }
+            return `${id}`;
+        }), ",");
+        if (inspected.has(signature))
+            return undefined;
+        inspected.add(signature);
+        const fields = Array.flatMap(expanded, (member) => schemaEntries(member.properties));
+        const collision = collidingProperties([...Array.map(fields, ([name]) => name), ...additionalNames], true);
+        if (collision)
+            return collision;
+        const grouped = new Map();
+        Array.forEach(fields, ([name, nested]) => grouped.set(name, Array.append(grouped.get(name) ?? [], nested)));
+        const nestedCollision = Array.reduce(grouped.values(), undefined, (found, group) => found ?? (group.length > 1 ? inspect(group) : undefined));
+        if (nestedCollision)
+            return nestedCollision;
+        const items = Array.flatMap(expanded, (member) => schemaList(member.items));
+        const itemCollision = items.length > 1 ? inspect(items) : undefined;
+        if (itemCollision)
+            return itemCollision;
+        const additional = Array.flatMap(expanded, (member) => schemaList(member.additionalProperties));
+        return additional.length > 1 ? inspect(additional) : undefined;
+    };
+    return inspect([schema], extraNames);
+}
+const schemaMapKeywords = new Set(["properties", "patternProperties", "dependentSchemas", "$defs"]);
+const schemaKeywords = new Set([
+    "additionalProperties",
+    "unevaluatedProperties",
+    "items",
+    "unevaluatedItems",
+    "contains",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+]);
+const schemaListKeywords = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+/** A subschema position holds an object or a boolean; anything else is left alone. */
+function camelCaseSubschema(value) {
+    return Predicate.isBoolean(value) || Predicate.isObject(value) ? camelCaseSchema(value) : value;
+}
+function camelCaseName(value) {
+    return Predicate.isString(value) ? propertyName(value, true) : value;
+}
+function camelCaseNames(value) {
+    return Array.isArray(value) ? Array.map(value, camelCaseName) : value;
+}
+function mapEntries(value, f) {
+    return Predicate.isObject(value)
+        ? Record.fromEntries(Array.map(Record.toEntries(value), f))
+        : value;
+}
+function camelCaseKeyword(keyword, value) {
+    switch (keyword) {
+        case "properties":
+        case "dependentSchemas":
+            return mapEntries(value, ([name, part]) => [
+                propertyName(name, true),
+                camelCaseSubschema(part),
+            ]);
+        case "required":
+            return camelCaseNames(value);
+        case "dependentRequired":
+            return mapEntries(value, ([name, names]) => [
+                propertyName(name, true),
+                camelCaseNames(names),
+            ]);
+        case "discriminator":
+            return Predicate.isObject(value) && Predicate.isString(value.propertyName)
+                ? { ...value, propertyName: propertyName(value.propertyName, true) }
+                : value;
+    }
+    if (schemaMapKeywords.has(keyword))
+        return mapEntries(value, ([name, part]) => [name, camelCaseSubschema(part)]);
+    if (schemaKeywords.has(keyword))
+        return camelCaseSubschema(value);
+    if (schemaListKeywords.has(keyword))
+        return Array.isArray(value) ? Array.map(value, camelCaseSubschema) : value;
+    return value;
+}
+/**
+ * Rename snake_case property names to camelCase throughout a schema tree.
+ *
+ * Renames `properties` keys, `required` entries, `dependentRequired` keys and values,
+ * `dependentSchemas` keys, and `discriminator.propertyName` with `propertyName(name, true)`, and
+ * recurses into every subschema. Values such as `enum`, `const`, `default`, and `examples`,
+ * `patternProperties` keys, and `$ref`s keep their spelling. References are not resolved and
+ * collisions are not detected; use `schemaPropertyCollision` first. The input is not modified.
+ */
+export function camelCaseSchema(schema) {
+    if (Predicate.isBoolean(schema))
+        return schema;
+    return Record.fromEntries(Array.map(Record.toEntries(schema), ([keyword, value]) => [
+        keyword,
+        camelCaseKeyword(keyword, value),
+    ]));
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { decode, ParsedServiceFromParsedOpenApi } from "./decode.ts";
+export { camelCaseSchema, collidingProperties, propertyName, schemaPropertyCollision, } from "./case.ts";
 export * from "./model/index.ts";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { decode, ParsedServiceFromParsedOpenApi } from "./decode.js";
+export { camelCaseSchema, collidingProperties, propertyName, schemaPropertyCollision, } from "./case.js";
 export * from "./model/index.js";