@abapify/acds

ABAP CDS source parser — tokenizer, parser, and typed AST for DDL-based ABAP source types.

Overview

Parses .acds (ABAP CDS DDL) source code into a fully typed Abstract Syntax Tree. Built on Chevrotain for fast, error-recovering parsing.

Supported Definitions

| CDS Construct | AST Node | Example | | --------------- | -------------------------- | ----------------------------------------------------------------------------- | | Table | TableDefinition | define table [entity] ztable { ... } | | Root table ent. | TableDefinition | define root table entity ztable { ... } | | Structure | StructureDefinition | define structure zstruct { ... } | | Simple type | SimpleTypeDefinition | define type ztype : abap.char(10); | | View entity | ViewEntityDefinition | define [root] view entity zv as select ... | | Legacy view | ViewEntityDefinition | define view zv as select ... (legacy) | | Abstract entity | AbstractEntityDefinition | define abstract entity zae { ... } | | Custom entity | CustomEntityDefinition | define custom entity zce { ... } | | External entity | ExternalEntityDefinition | define external entity zee { ... } with federated data provided at runtime; | | Table function | TableFunctionDefinition | define table function ztf returns { ... } | | Scalar function | ScalarFunctionDefinition | define scalar function zsf ... | | Hierarchy | HierarchyDefinition | define hierarchy zh as parent child hierarchy(...) { ... } | | Aspect | AspectDefinition | define aspect za { ... } | | Annotation | AnnotationDefinition | define annotation za: Boolean; | | Access policy | AccessPolicyDefinition | define accesspolicy zap { ... } | | Service | ServiceDefinition | define service zsvc { ... } | | Extension | ExtensionDefinition | extend view entity zv with { ... } | | Metadata ext. | MetadataExtension | annotate entity ZView with { ... } | | Role (DCL) | RoleDefinition | define role zr { grant select ... } |

Parser Features

• Error recovery — returns partial AST + structured errors on invalid input
• Full annotation support — strings, enums, booleans, numbers, arrays, objects
• Built-in types — abap.char(10), abap.dec(11,2), abap.dats, etc.
• Named types — data element and qualified name references
• Include directives — include <structure> with optional suffix
• Comments — line (//, --) and block (/* */) comments are skipped
• Case-insensitive keywords — DEFINE VIEW ENTITY and define view entity both parse; identifiers keep their original spelling
• FROM clause — join chains, parameterized sources, FROM associations
• View flavours — define view entity <name> and the legacy define view <name>
• Projection elements — paths, calls (coalesce(a, b), sum(x)) and cast(x as type [preserving type])

Installation

bun add @abapify/acds

Quick Start

import { parse } from '@abapify/acds';

const result = parse(`
  @AbapCatalog.tableCategory : #TRANSPARENT
  @AbapCatalog.deliveryClass : #A
  define table ztable {
    key mandt : abap.clnt not null;
    key field1 : abap.char(10) not null;
    field2 : some_data_element;
  }
`);

if (result.errors.length === 0) {
  const table = result.ast.definitions[0]; // TableDefinition
  console.log(table.kind); // 'table'
  console.log(table.name); // 'ztable'
  console.log(table.members); // [FieldDefinition, FieldDefinition, ...]
  console.log(table.annotations); // [Annotation, Annotation]
}

API

parse(source: string): ParseResult

Parses a CDS source string through the full pipeline: tokenize → parse → visit.

interface ParseResult {
  /** The parsed AST (may be partial if there are errors) */
  ast: CdsSourceFile;
  /** Lexing and parsing errors */
  errors: CdsParseError[];
}

AST Types

Root

interface CdsSourceFile {
  definitions: CdsDefinition[];
}

type CdsDefinition =
  | TableDefinition
  | StructureDefinition
  | SimpleTypeDefinition
  | ViewEntityDefinition
  | AbstractEntityDefinition
  | CustomEntityDefinition
  | ExternalEntityDefinition
  | TableFunctionDefinition
  | ScalarFunctionDefinition
  | HierarchyDefinition
  | AspectDefinition
  | AnnotationDefinition
  | AccessPolicyDefinition
  | ServiceDefinition
  | ExtensionDefinition
  | MetadataExtension
  | RoleDefinition;

Definitions

interface TableDefinition {
  kind: 'table';
  name: string;
  annotations: Annotation[];
  members: TableMember[]; // FieldDefinition | IncludeDirective
}

interface StructureDefinition {
  kind: 'structure';
  name: string;
  annotations: Annotation[];
  members: TableMember[];
}

interface SimpleTypeDefinition {
  kind: 'simpleType';
  name: string;
  annotations: Annotation[];
  type: TypeRef;
}

interface ServiceDefinition {
  kind: 'service';
  name: string;
  annotations: Annotation[];
  exposes: ExposeStatement[];
}

interface MetadataExtension {
  kind: 'metadataExtension';
  entity: string;
  annotations: Annotation[];
  elements: AnnotatedElement[];
}

Fields & Types

interface FieldDefinition {
  annotations: Annotation[];
  name: string;
  type: TypeRef;
  isKey: boolean;
  notNull: boolean;
}

type TypeRef = BuiltinTypeRef | NamedTypeRef;

// abap.char(10), abap.dec(11,2)
interface BuiltinTypeRef {
  kind: 'builtin';
  name: string;
  length?: number;
  decimals?: number;
}

// Data element or qualified name
interface NamedTypeRef {
  kind: 'named';
  name: string;
}

Annotations

interface Annotation {
  key: string;
  value: AnnotationValue;
}

type AnnotationValue =
  | { kind: 'string'; value: string }
  | { kind: 'enum'; value: string } // #TRANSPARENT → 'TRANSPARENT'
  | { kind: 'boolean'; value: boolean }
  | { kind: 'number'; value: number }
  | { kind: 'array'; items: AnnotationValue[] }
  | { kind: 'object'; properties: AnnotationProperty[] };

FROM clause (view entities)

interface ViewEntityDefinition {
  kind: 'viewEntity';
  name: string;
  annotations: Annotation[];
  legacy?: boolean; // true for the legacy `define view <name>` syntax
  root?: boolean; // `define root view entity`
  writable?: boolean; // `define writable view entity`
  providerContract?: string; // `provider contract transactional_query`
  sourceKind: DataSourceKind; // 'select' | 'projection'
  distinct?: boolean; // `select distinct`
  source: DataSource; // the root data source
  joins: JoinClause[]; // ordered join chain — empty when there are no joins
  fromAssociations?: AssociationDeclaration[]; // associations of the FROM region
  aspectBindings?: AspectBinding[]; // `bind aspect` bindings
  parameters: ParameterDefinition[];
  members: ViewMember[];
  where?: Expression;
  groupBy?: string[];
  having?: Expression;
  setOperations?: SetOperation[]; // union/intersect/except branches
}

interface DataSource {
  name: string;
  alias?: string;
  parameters?: DataSourceParameter[]; // parameterized source
}

interface DataSourceParameter {
  name: string; // e.g. 'P_StartDate'
  value: string; // raw binding: ':P_Key1StartDate', '$session.client', "'X'"
}

type JoinType = 'inner' | 'leftOuter' | 'rightOuter' | 'fullOuter' | 'cross';

// Conditioned joins always carry an ON condition — the grammar enforces it.
interface ConditionedJoinClause {
  kind: 'join';
  joinType: 'inner' | 'leftOuter' | 'rightOuter' | 'fullOuter';
  source: JoinSource; // DataSource | JoinGroup
  on: Expression; // the ON condition (opaque)
  cardinality?: WordCardinality; // `many to one join` / `to one join`
}

// A cross join never carries an ON condition.
interface CrossJoinClause {
  kind: 'join';
  joinType: 'cross';
  source: JoinSource;
}

type JoinClause = ConditionedJoinClause | CrossJoinClause;

// A join source is either a plain data source or a parenthesized group.
type JoinSource = DataSource | JoinGroup;

// `join (A join B on …) on …` — the group acts as a single join source.
interface JoinGroup {
  kind: 'joinGroup';
  source: JoinSource; // nested — may itself be a group
  joins: JoinClause[]; // the join chain inside the parentheses
}

Supported join spellings (normalized to JoinType):

| spelling | joinType | Notes | | ------------------ | ------------ | -------------------------------- | | JOIN | inner | | | INNER JOIN | inner | | | LEFT JOIN | leftOuter | OUTER is optional | | LEFT OUTER JOIN | leftOuter | | | RIGHT JOIN | rightOuter | OUTER is optional | | RIGHT OUTER JOIN | rightOuter | | | FULL JOIN | fullOuter | OUTER is optional | | FULL OUTER JOIN | fullOuter | | | CROSS JOIN | cross | must not carry an ON condition |

The ON condition is required for inner and outer joins and not allowed for a cross join — the grammar enforces this.

The accepted join syntax is the same for every view flavour: a CDS view entity (define view entity) and a classic SQL view (define view) accept exactly the same spellings. FULL [OUTER] JOIN is the SQL-standard full outer join — it is not part of the ABAP CDS DDL join syntax, but it is supported so that HANA CDS / CAP CDS sources (which use the standard SQL join syntax) can be read with the same parser.

Example:

const { ast } = parse(`
  define view entity ZC_Cube as select from I_Item as _Item
    left outer join ZI_Other as _Other
      on _Item.key = _Other.key
    association [0..1] to I_Product as _Product
      on $projection.Product = _Product.Product
  {
    key _Item.key
  }
`);

const view = ast.definitions[0] as ViewEntityDefinition;
view.joins[0].joinType; // 'leftOuter'
view.joins[0].source.alias; // '_Other'
view.fromAssociations?.[0].target; // 'I_Product'

Errors

interface CdsParseError {
  message: string;
  line: number;
  column: number;
  offset: number;
  length: number;
}

Architecture

Source string
  → CdsLexer (Chevrotain Lexer)     tokens.ts
  → CdsParser (Chevrotain CstParser) parser.ts
  → CdsVisitor (CST → AST)           visitor.ts
  → CdsSourceFile                     ast.ts

| Module | Responsibility | | ------------ | ----------------------------------------------- | | tokens.ts | Token definitions (keywords, symbols, literals) | | parser.ts | Grammar rules (CST production) | | visitor.ts | CST → typed AST transformation | | ast.ts | AST node type definitions | | errors.ts | Error normalization (lex + parse) | | index.ts | parse() entry point + re-exports |

Roadmap

• ✅ DDL: tables, structures, simple types, view entities (define [root] view entity, projection views + provider contract), legacy define view, abstract/custom/table/external entities, table/scalar functions, hierarchies, aspects (DRAS), DDLA annotation definitions, access policies, services (SRVD), metadata extensions (DDLX), extend view/entity forms, parameters, associations, compositions
• ✅ DCL: role definitions — switchable, grant-select + where, with optional elements, combination mode and|or|redefinition, inherit, inheriting conditions
• ✅ Annotations: full value grammar (strings, enums, booleans, numbers, arrays, objects, dotted keys)
• ✅ Tooling: AST walker helpers, semantic validators (SemanticDiagnostic), grammar coverage metadata
• ✅ FROM clause: join chains (inner, left [outer], right [outer], full [outer], cross) with word cardinalities and grouped joins, parameterized sources, FROM associations, path-expression data sources (_assoc[ ... ]), bind aspect
• ✅ Elements: case … end, arithmetic, casts, calls (incl. f()), window over (…), paths, : localized, : redirected to, distinct, where/group by/having, union [all]/intersect/except
• 🔜 Expression grammar (structured on/where trees — currently opaque { source, tokens })
• 🔜 BDEF / behavior definitions (owned by epic E10)

Dependencies

• chevrotain — Parser toolkit (lexer + CstParser + visitor)