@odata-effect/odata-effect-generator

Code generator for Effect-based OData service clients. It reads an OData $metadata XML file and generates TypeScript schemas, CRUD services, path builders, query helpers, and operations.

This is the recommended starting point for a new project because it turns service metadata into typed code.

Install

Install it in the app or workspace where you want to generate code:

pnpm add -D @odata-effect/odata-effect-generator
pnpm add @odata-effect/odata-effect @odata-effect/odata-effect-promise [email protected] @effect/[email protected]

Step 1: Download Metadata

Save your service metadata as XML:

curl 'https://server.example.com/sap/opu/odata/sap/MY_SERVICE/$metadata' -o metadata.xml

If the endpoint needs authentication, download the same $metadata document using your normal authenticated HTTP client and save it locally.

Step 2: Generate Code

Generate files directly into an existing app:

pnpm exec odata-effect-gen generate ./metadata.xml ./src/generated --files-only --force --config '{"esmExtensions": true}'

Generate a package-style folder instead:

pnpm exec odata-effect-gen generate ./metadata.xml ./packages/my-service-client --package-name @my-org/my-service-client --force

Use --files-only for application source folders. Omit it when you want the generator to create package files such as package.json, tsconfig, and vitest.config. Package-style output is intended for workspace layouts where the generated package can share the repository's TypeScript and build configuration.

Step 3: Call The Generated Client

Promise-style application code:

import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
import { createODataRuntime, toPromise } from "@odata-effect/odata-effect-promise"
import { ProductService } from "./generated/index.js"

const runtime = createODataRuntime(
  {
    baseUrl: "https://server.example.com",
    servicePath: "/sap/opu/odata/sap/MY_SERVICE/"
  },
  NodeHttpClient.layer
)

try {
  const products = await ProductService.getAll({ $top: 10 }).pipe(toPromise(runtime))
  const product = await ProductService.getById("123").pipe(toPromise(runtime))
  console.log({ product, products })
} finally {
  await runtime.dispose()
}

Effect-style code:

import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
import { Config } from "@odata-effect/odata-effect"
import * as Effect from "effect/Effect"
import * as Layer from "effect/Layer"
import { ProductService } from "./generated/index.js"

const Live = Layer.merge(
  Layer.succeed(Config.ODataClientConfig, {
    baseUrl: "https://server.example.com",
    servicePath: "/sap/opu/odata/sap/MY_SERVICE/"
  }),
  NodeHttpClient.layer
)

const program = ProductService.getAll({ $top: 10 })
const products = await Effect.runPromise(program.pipe(Effect.provide(Live)))

Generated service names are based on entity set names. For example, an entity set named Products becomes ProductService.

Generated models use TypeScript-style property names such as name or productID. The generated schemas handle encoding and decoding the original OData property names for you.

Generated Files

| File | Description | | ---- | ----------- | | Models.ts | Compatibility facade re-exporting model schema values and types. | | Models.<Type>.ts | Runtime schema for one entity, complex type, or enum, with its existing create/editable/ID variants. | | QueryModels.ts | Type-safe query builders for filter, select, expand, V4 nested expanding, orderby, top, and skip. | | Services.ts | Compatibility facade for CRUD services and standalone functions. | | Services.<EntitySet>.ts | CRUD service and functions for one entity set. | | PathBuilders.ts | Tree-shakable navigation path builders with terminal fetch helpers. | | Operations.ts | Compatibility facade for unbound operations, when present. | | Operations.<FunctionName>.ts | One function import, V4 function, or V4 action. | | index.ts | Re-exports the generated API. |

Service Functions

Use generated services for normal CRUD operations:

const products = await ProductService.getAll({ $top: 10 }).pipe(toPromise(runtime))
const product = await ProductService.getById("123").pipe(toPromise(runtime))
const created = await ProductService.create({ name: "Notebook" }).pipe(toPromise(runtime))
await ProductService.update("123", { name: "Updated" }).pipe(toPromise(runtime))
await ProductService.delete("123").pipe(toPromise(runtime))

Path Builders

Use path builders when you need typed navigation across relationships:

import { pipe } from "effect/Function"
import { Flight, People, byKey, fetchCollection, planItems, trips } from "./generated/index.js"

const flights = await pipe(
  People,
  byKey("russellwhyte"),
  trips,
  byKey(0),
  planItems,
  fetchCollection(Flight),
  toPromise(runtime)
)

The path type tracks both the current entity type and whether the path is a collection, so TypeScript rejects invalid navigation.

Type-Safe Queries

Use generated query models instead of hand-written query strings when possible:

import { productQuery } from "./generated/index.js"

const query = productQuery()
  .filter((q) => q.name.contains("Notebook"))
  .orderBy((q) => q.name.asc())
  .select("productID", "name")
  .top(10)
  .build()

const products = await ProductService.getAll(query).pipe(toPromise(runtime))

For OData V4 services, use expanding when an expanded navigation target needs its own select, filter, ordering, or paging options:

import { PersonService, personQuery } from "./generated/index.js"

const query = personQuery()
  .select("userName")
  .expanding("trips", (trips, qTrip) =>
    trips
      .select("description", "budget")
      .filter(qTrip.budget.gt(1000))
      .orderBy(qTrip.startsAt.desc())
      .top(5)
  )
  .build()

const people = await PersonService.getAll(query).pipe(toPromise(runtime))

The expanded builder is typed from the generated navigation property. In the example above, the callback receives a trip query builder and the generated trip query paths, while the final query still uses the original OData path names. For V2 services, use regular expand("trips"); nested expanding(...) emits V4 inline expand options.

Attach query options inside path-builder pipes with withQueryOptions:

import { pipe } from "effect/Function"
import { People, Trip, byKey, fetchCollection, trips, withQueryOptions } from "./generated/index.js"

const myTrips = await pipe(
  People,
  byKey("russellwhyte"),
  trips,
  withQueryOptions({
    $filter: "budget gt 1000",
    $orderby: "startsAt desc"
  }),
  fetchCollection(Trip),
  toPromise(runtime)
)

Operations

If the metadata contains FunctionImports, Functions, or Actions, they are exported from Operations.ts:

import { Operations } from "./generated/index.js"

const result = await Operations.getProductsByRating({ rating: 5 }).pipe(toPromise(runtime))
await Operations.resetDataSource().pipe(toPromise(runtime))

CLI Reference

odata-effect-gen generate <metadata-path> <output-dir> [options]

| Option | Description | | ------ | ----------- | | --service-name <name> | Override the service name. Defaults to the EntityContainer name. | | --package-name <name> | Package name for package-style workspace generation. | | --force | Overwrite existing files. | | --files-only | Generate only source files directly into output-dir. | | --config <json-or-path> | JSON string or path to JSON config. Supports esmExtensions and naming overrides. |

Example config file:

{
  "esmExtensions": true,
  "overrides": {
    "properties": {
      "ID": "id",
      "SKU": "sku"
    },
    "entities": {
      "BusinessPartner": {
        "name": "Partner"
      }
    }
  }
}

Run with:

pnpm exec odata-effect-gen generate ./metadata.xml ./src/generated --files-only --config ./odata-effect.config.json

Troubleshooting

| Problem | What to check | | ------- | ------------- | | Generated imports fail in Node ESM | Use --config '{"esmExtensions": true}'. | | ProductService does not exist | Check the entity set name in metadata; service names are singularized from entity sets. | | Request URL is wrong | baseUrl should be host only; servicePath should be the OData service root; generated paths are relative. | | Metadata download fails | Download $metadata with the same authentication method your SAP service requires. |

License

MIT

Tree shaking generated clients

Granular runtime modules are the default for CLI and generate output. Existing imports from Models, Operations, Services, PathBuilders, and index remain valid. index still exports the established Operations namespace. No new configuration option or import migration is required. Low-level single-file functions such as generateModels retain their existing return format; tools assembling output themselves can use generateSourceFiles for the granular layout.

Each model module imports only schemas referenced by its structural or navigation properties. Inherited fields are already resolved by the metadata digester. Collection elements, enums and nested types participate in the same dependency closure. Typed Schema.suspend boundaries handle self references and mutual cycles, including structural properties used by editable inputs. Editable/create schemas retain their existing nested-model semantics. Query models and path builders have only type imports of models and introduce no runtime schema dependency.

Prefer named imports, including through the compatibility facades:

import { getProductsByRating } from "./generated/Operations.js"
import { ProductService, getAllProduct } from "./generated/Services.js"

For an explicit narrow module entry point, import directly:

import { getProductsByRating } from "./generated/Operations.getProductsByRating.js"
import { ProductService } from "./generated/Services.Products.js"
import { Product } from "./generated/Models.Product.js"

Names follow naming overrides. Filenames are allocated deterministically, with numeric suffixes where needed to avoid case-insensitive or sanitized-name collisions; the facades always point to the allocated filenames.

Regenerate the complete output with --force, and include all generated files when copying or publishing a client. Prefer a clean generated directory when metadata types are removed or renamed, since generation does not delete old files. esmExtensions retains its behavior: true emits .js relative specifiers, false emits extensionless specifiers. Package mode defaults to true and --files-only defaults to false; explicit configuration wins in both modes.

Rollup integration tests use synthetic metadata with 24 unrelated entity roots. They verify that single-operation and service imports exclude unrelated schema markers, and that direct module imports never load those roots even with purity comments removed. Path imports retain no generated runtime schemas. These are fixture results, not measurements of consuming applications.

Tree shaking still depends on consumer bundler configuration and package side-effect metadata. Generated packages declare sideEffects: false. Files-only consumers control their own package configuration. Whole namespace objects passed around or accessed dynamically may intentionally retain more exports. Facades also evaluate all their re-exported modules in unbundled ESM. Existing purity comments complement the module boundaries and help bundlers drop unused facade exports and variants; keep them during intermediate transpilation. Shared Effect/OData runtime code and the selected schema's recursive dependency closure remain necessary.

Projected reads

When using $select (including inside $expand), supply a schema for the actual response rather than the full generated entity:

const summary = Schema.Struct({ id: Schema.Number }).pipe(Schema.encodeKeys({ id: "ID" }))
const rows = yield* ProductService.getAllWithSchema(summary, productQuery().select("iD").build())
// rows contain only { id: number }

getByIdWithSchema(id, schema, options) supports single-entity projections. The standalone equivalents are getAllProductWithSchema(schema, options) and getByIdProductWithSchema(id, schema, options). Supply nested schemas for nested expanded projections. Ordinary generated reads reject $select before sending HTTP; low-level core reads already accept an explicit response schema.

Create and update inputs

Each entity has a CreateEntity schema/type for creation and separate EditableEntity / PartialEditableEntity schemas for updates. Create inputs include writable primary keys; update inputs exclude keys. Inline Core.Computed / Org.OData.Core.V1.Computed annotations exclude server-generated fields, while SAP sap:creatable / sap:updatable flags and inline Core.Immutable govern write eligibility. Regenerate clients to use these schemas.

For manual CRUD factories, createSchema is optional and defaults to the existing editableSchema, preserving existing clients.

Standalone packages

Without --files-only, generation creates a self-contained ESM package. Run npm install, npm run check and npm run build in the output directory. The package emits JavaScript and declarations under dist, exports subpaths, and keeps purity comments for bundlers. It needs no parent tsconfig or sibling workspace packages. Package mode defaults to .js extensions in relative imports. The generated client requires core version 1.3.1 or newer for the generated APIs.