How openwallet-foundation-labs/dcql-ts works
Project type and purpose
• This is an open-source TypeScript library (DCQL) that implements the Digital Credentials Query Language.
• Its goal is to let client applications construct, parse, execute, and validate JSON-encoded queries over Verifiable Presentations.
• It is platform-agnostic and can run in Node.js, React Native, or browser environments.
File structure
• At the root you have monorepo files (.changeset, pnpm-workspace.yaml, turbo.json) and a single package under /dcql.
• Inside /dcql/src you see five major subdirectories:
• dcql-parser
• dcql-query
• dcql-query-result
• dcql-presentation
• dcql-error
• An index.ts re-exports the public API (DcqlQuery, DcqlQueryResult, etc.).
• There are tests alongside parser, query, and presentation modules.
• Config files (tsconfig.json, package.json) and CI/CD scripts (GitHub workflows) handle building, testing, and releasing.
README insights
• Confirms that this is a pure library, not a full application.
• Emphasizes JSON-encoded queries and validation of Verifiable Presentations.
• Mentions supported environments and contribution guidelines.
Main components & interactions
a. External “Client App”
• Imports DCQL package
• Builds or loads a JSON-formatted DCQL query
• Supplies Verifiable Presentations (VCs) to the library
• Receives a DcqlQueryResult indicating which credentials matched and any errors
• Parser module
• Parses JSON into an AST or internal model
• Query module
• Provides classes (DcqlQuery, m-models) for programmatic query construction
• Query-Result module
• Executes the query over input credentials; produces DcqlQueryResult
• Presentation module
• Validates/verifies presentations against query requirements
• Error module
• Defines error types (DCErrors) thrown at parsing or runtime
c. Data flow
1. Client → (JSON query) → Parser
2. Parser → (AST/model) → Query Executor
3. Executor + input credentials → Query-Result
4. Result → Presentation Validator → Final DcqlQueryResult
5. Errors bubble up via the Error module
Architectural patterns & design principles
• Modular separation by concern: parsing, query-building, execution, result processing, error handling.
• Public API layer (index.ts) hides internal module structure.
• Test harnesses alongside each module enforce correctness.
• CI/CD ensures build/test/release automation.