Taxi

https://taxilang.org/docs
Admin
Taxi is a language for documenting and connecting data and services across an ecosystem, focusing on...
Tokens:46,872
Snippets:405
Trust Score:6.5
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install Taxi CLI using SDKMAN

Source: https://taxilang.org/docs/taxi-cli/taxi-cli-intro

Instructions to install the Taxi CLI using the SDKMAN package manager. This is the primary method for obtaining the tool.

```shell
sdk i taxi
taxi
```

--------------------------------

### Taxi Project Configuration Example (taxi.conf)

Source: https://taxilang.org/docs/taxi-cli/taxi-cli-intro

An example of a `taxi.conf` file, which uses the HOCON format to describe project layout and plugins. This file is essential for configuring Taxi projects.

```hocon
name: demo/hello-world
version: 0.1.0
sourceRoot: src/
```

--------------------------------

### Configuring Taxi Repositories

Source: https://taxilang.org/docs/packages/taxi-projects

Provides an example of how to define repositories in `taxi.conf` for downloading and publishing Taxi dependencies. This example shows configuration for a Sonatype Nexus repository.

```hocon
repositories: [ 
   { 
      // The name of the repository.  Optional, but used to reference credentials 
      name: "my-corporate-nexus", 
      url: "http://localhost:8081", 
      // Optional.  Defines the type of repository being used.  Currently only 'nexus' is supported, 
      // so this can be omitted. 
      type : "nexus", 

      // Settings specific to the repository provider. 
      // Below settings shown are applicable to a nexus repository 
      settings: { 
         // The name of the repository as defined within nexus 
         repositoryName : taxi 
      } 
   } 
]
```

--------------------------------

### Taxi Project Structure Example

Source: https://taxilang.org/docs/taxi-cli/taxi-cli-intro

A typical file and directory layout for a Taxi project. It includes a source directory for `.taxi` files and a `taxi.conf` configuration file.

```tree
project/
├── src/
│   ├── someTypes.taxi
│   └── moreTypes.taxi
└── taxi.conf
```

--------------------------------

### HTTP Operations Example

Source: https://taxilang.org/docs/language/services

Examples of defining various HTTP operations (GET, POST, PUT) within a service.

```APIDOC
## HTTP Operations Example

### Description
Defines an `OrderApi` service with operations for listing orders (GET), creating an order (POST with body), and updating order status (PUT with path parameter and body).

### Method
N/A (Taxi Service Definition)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```taxi
service OrderApi {
   // GET request
   @HttpOperation(method = "GET", url = "/orders")
   operation listOrders():Order[]
   
   // POST with request body
   @HttpOperation(method = "POST", url = "/orders")
   operation createOrder( @HttpRequestBody order: CreateOrderRequest ):Order
   
   // PUT with path parameter
   @HttpOperation(method = "PUT", url = "/orders/{orderId}/status")
   operation updateStatus(
      @PathVariable(name = "orderId") id: OrderId,
      @HttpRequestBody status: OrderStatus
   ):Order
}
```
```

--------------------------------

### Valid and Invalid Taxi Annotation Inheritance Examples

Source: https://taxilang.org/docs/language/annotations

Illustrates the rules for annotation inheritance in Taxi, showing valid examples of annotations inheriting from other annotations and invalid examples of types inheriting from annotations or vice-versa.

```Taxi
// ✅ Valid: Annotation inheriting from annotation
annotation BaseRule {
    message: String
}

annotation ValidationRule inherits BaseRule {
    errorCode: Int
}

// ❌ Invalid: Type inheriting from annotation
// type CustomerId inherits ValidationRule  // Compilation error

// ❌ Invalid: Annotation inheriting from type
// annotation MyAnnotation inherits String  // Compilation error
```

--------------------------------

### String Padding at Start in Taxi StdLib

Source: https://taxilang.org/docs/language/stdlib

Pads a string at the start to a specified length using a given character or space. If multiple characters are provided for padding, only the first is used. This is an extension function for strings.

```Taxi
declare extension function padStart(input: String, length: Int, padWith: String):String
```

--------------------------------

### Operation Contracts Example

Source: https://taxilang.org/docs/language/services

Demonstrates defining operation contracts for expected behavior.

```APIDOC
## Operation Contracts Example

### Description
Illustrates defining contracts for operations, such as ensuring output currency matches a target or deriving output from input.

### Method
N/A (Taxi Operation Definition)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```taxi
model Money {
   currency : CurrencyCode
   amount : Decimal
}

// Contract ensures output currency matches targetCurrency
operation convertCurrency(
   input: Money,
   targetCurrency: CurrencyCode
) : Money(currency = targetCurrency)

// Contract specifies output derives from input
operation normalizeAddress(
   input: Address
) : NormalizedAddress( from input )
```
```

--------------------------------

### Named Queries in Taxilang

Source: https://taxilang.org/docs/taxiql/querying

Demonstrates how to define and use named queries for saving and reusing query logic. Includes examples of simple named queries and parameterized queries.

```Taxilang
// Simple named query
query PendingOrders {
   find { Order[](Status == 'PENDING') }
}
```

```Taxilang
// Parameterized query
query FindOrdersByStatus(status: OrderStatus) {
   find { Order[](Status == status) }
}
```

--------------------------------

### TaxiQL Model Inheritance Example

Source: https://taxilang.org/docs/language/models

Provides an example of model inheritance, where an `Employee` model inherits properties from a `PersonBase` model. The documentation advises preferring composition over inheritance.

```TaxiQL
model PersonBase {
    id: PersonId
    firstName: FirstName
    lastName: LastName
}

model Employee inherits PersonBase {
    employeeId: EmployeeId
    department: DepartmentName
}
```

--------------------------------

### Taxi Project Directory Structure Example

Source: https://taxilang.org/docs/packages/taxi-projects

Illustrates a typical file and directory layout for a Taxi project, including source files, test configurations, and the main project configuration file.

```tree
. 
├── src/ 
│   └── sample.taxi 
├── tests/ 
│   └── hello-world/ 
│       ├── hello-world.spec.json 
│       ├── input.csv 
│       └── expected-output.json 
└── taxi.conf
```

--------------------------------

### Example Output of TaxiLang Project Publishing Command

Source: https://taxilang.org/docs/packages/publishing

Demonstrates the expected output when running the `taxi publish` command, showing the files being added, the artifact being prepared, and the successful upload to the Nexus repository with basic authentication.

```bash
$  taxi publish
Taxi version @22a6a51
Adding file /sample-project/taxi.conf
Adding file /sample-project/src/Test-enum.taxi
Adding file /sample-project/src/sub-src/Test-C.taxi
Adding file /sample-project/src/Test-D.taxi
Adding file /sample-project/src/Test-B.taxi
Adding file /sample-project/src/Test-A.taxi
Publishing package taxi/sample/0.3.0 from /tmp/sample-0.3.0.zip to http://localhost:8081/
Will attempt to publish to http://localhost:8081//repository/taxi/taxi/sample/0.3.0/sample-0.3.0.zip using basic auth credentials supplied
Artifact uploaded successfully

```

--------------------------------

### Taxi Service Definition Example

Source: https://taxilang.org/docs/language/semantic-types

Presents an example of a Taxi service definition. Services specify the exact semantic types they accept as input and return as output. This example shows a `PaymentService` with operations that take `Money`, `Currency`, and `AccountId`, returning a `TransactionId`.

```Taxi
service PaymentService {
    operation processPayment(
        amount: Money,
        currency: Currency,
        accountId: AccountId
    ): TransactionId
}
```

--------------------------------

### Taxi Project Configuration File (taxi.conf) Example

Source: https://taxilang.org/docs/packages/taxi-projects

Demonstrates the structure of a `taxi.conf` file, which defines project metadata, source roots, and plugin configurations, including settings for invoking the Taxi Kotlin plugin with Maven details.

```hocon
name: taxi/maven-sample
version: 0.3.0
sourceRoot: src/ 
plugins: { 
   taxi/kotlin: { 
      maven: { 
         groupId: "lang.taxi" 
         artifactId: "parent" 
         repositories: [ 
            { 
               id: "internal-repo" 
               url: "https://newcorp.nexus.com" 
               snapshots: true 
            } 
         ] 
      } 
   } 
}
```

--------------------------------

### Defining Repository Credentials

Source: https://taxilang.org/docs/packages/taxi-projects

Illustrates how to define credentials for authenticating with remote repositories in the `taxi.conf` file. It shows an example for a Nexus repository with username and password.

```hocon
credentials: [ 
   { repositoryName: "nexus", username: "jimmy", password: "pass123" } 
]
```

--------------------------------

### TaxiQL Query Example with Semantic Types

Source: https://taxilang.org/docs/language/semantic-types

Demonstrates how TaxiQL queries can utilize semantic types for precise data discovery. This example shows a query that retrieves `Transaction` objects and specifies derived fields like `amountInUsd`, allowing the system to handle currency conversions automatically.

```TaxiQL
find { Transaction[] } as {
    id: TransactionId
    amount: Money
    // System knows to look for Currency conversion if needed
    amountInUsd: Money(currency = "USD")
}[]
```

--------------------------------

### Basic Service Definition

Source: https://taxilang.org/docs/language/services

A basic example of defining a service in Taxi to represent APIs and data sources.

```APIDOC
## Basic Service Definition

### Description
Defines a service named `CustomerApi` with operations to retrieve customer data.

### Method
N/A (Taxi Service Definition)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```taxi
service CustomerApi {
   // Get a customer by their ID
   operation getCustomer(CustomerId):Customer
   
   // List all customers
   operation listCustomers():Customer[]
}
```
```

--------------------------------

### Enrichment Pattern in TaxiQL

Source: https://taxilang.org/docs/taxiql/projections

A common TaxiQL pattern demonstrating how to enrich basic data with details from other sources and add calculated fields. This example starts with order data and enriches it with customer details and a calculated total.

```TaxiQL
// Start with basic order data
find { Order[] } as {
   orderId : OrderId
   // Enrich with customer details
   customerName : CustomerName
   customerEmail : EmailAddress
   // Add calculated fields
   totalWithTax : Decimal = OrderTotal * 1.2
}[]
```

--------------------------------

### Example Workflow: Taxonomy, Service, and Consumer Query (TaxiLang)

Source: https://taxilang.org/docs/language/adopting-semantic-types

Shows a typical workflow demonstrating the interaction between shared taxonomy, a service implementation, and a consumer query using TaxiQL. This highlights how semantic types facilitate data mapping and querying.

```TaxiLang
// In shared taxonomy
type CustomerId inherits String
type EmailAddress inherits String

// In service implementation
service CustomerService {
    operation getCustomer(CustomerId): Customer
}

// Consumer query using TaxiQL
find { Customer } as {
    id: CustomerId
    contact: EmailAddress
}
```

--------------------------------

### Taxi Project Configuration with OpenAPI Plugin

Source: https://taxilang.org/docs/taxi-cli/openapi-plugin

An example of a `taxi.conf` file showing project details like name, version, and source root, along with the configuration for the `taxi/open-api` plugin. It includes optional `outputPath` and `services` parameters for controlling where and which OpenAPI specs are generated.

```yaml
name: org.taxilang/demo
version: 0.1.0
sourceRoot: src/

plugins: {
   taxi/open-api: {
      outputPath: "open-api" // Optional
      services: ["PersonService"] // Optional
   }
}


```

--------------------------------

### Query Data with TaxiQL

Source: https://taxilang.org/docs/index

This example illustrates using TaxiQL, Taxi's query language, to find and combine data based on semantic relationships. It shows how to select data, project new fields, and perform aggregations like summing values.

```taxiql
// Find all customers and their orders
find { Customer[] } as {
    customerId : CustomerId
    name : concat(FirstName, ' ', LastName)
    orders: Order[]
    totalSpent: Decimal = Order[].sum((OrderValue) -> OrderValue)
}[]
```

--------------------------------

### Authenticating to Git Repositories for Taxi Dependencies

Source: https://taxilang.org/docs/packages/publishing

This example shows how to include authentication credentials directly in the dependency URL for private Git repositories. It demonstrates using a username and a Personal Access Token (PAT) for authentication. It also shows how to use environment variable substitution for sensitive credentials.

```taxi.conf
dependencies: {
    "com.orbitalhq/core" : "https://alexhamilton:glpat-dundadadadundundun@github.com/taxi-conf/reynolds-pamphlet.git"
}
```

```taxi.conf
dependencies: {
    // Note the variable is outside of quotes.
    "com.orbitalhq/core" : "https://"${GH_PAT}"@github.com/taxi-conf/reynolds-pamphlet.git"
}
```

--------------------------------

### Declare Taxi Plugins in taxi.conf

Source: https://taxilang.org/docs/taxi-cli/plugins

This snippet shows how to declare and enable plugins within the `plugins` section of the `taxi.conf` file. It includes an example for the 'taxi/kotlin' plugin and optional global plugin settings like repositories and local cache.

```yaml
plugins: {
    'taxi/kotlin': {  // Name of the plugin
        // plugin config goes here
    }
}
pluginSettings: { // Optional
    repositories: [
        'http://your-plugin-repository-url'
    ]
    localCache: '~/.taxi.plugins'
}
```

--------------------------------

### Adding Documentation to Taxi Types

Source: https://taxilang.org/docs/language/semantic-types

Shows how to add documentation to Taxi types using a specific comment syntax. This documentation explains the purpose and usage of the type, providing examples for clarity. It's crucial for shared understanding between systems.

```Taxi
[[ 
   ISO 3166-1 alpha-2 country code. 
   Example: "US", "GB", "FR"
]]
type CountryCode inherits String
```

--------------------------------

### Taxi External Function Declarations with Namespaces

Source: https://taxilang.org/docs/taxiql/functions

Demonstrates declaring external functions within a namespace in Taxi, including examples with type-based and named parameters.

```Taxi
namespace com.example {
   // Type-based parameters
   declare function concat(String, String): String
   declare function upperCase(String): String
   
   // With optional variable names
   declare function calculateTax(amount: Decimal, rate: TaxRate): Decimal
}
```

--------------------------------

### Conditional Composition in Taxi

Source: https://taxilang.org/docs/taxiql/functions

Demonstrates conditional logic within function composition in Taxi using the 'when' construct. This example calculates a price based on customer type.

```taxi
function calculatePrice(basePrice: Decimal, customerType: CustomerType): Decimal ->
   when {
      customerType == "VIP" -> basePrice * 0.8
      customerType == "Regular" -> basePrice * 0.95
      else -> basePrice
   }
```

--------------------------------

### Type Conversion for Mutations in TaxiLang

Source: https://taxilang.org/docs/taxiql/mutations

This example shows how TaxiLang automatically handles type conversion between source data models and the input requirements of mutation operations. It highlights how missing fields in the source can be handled by the target model.

```TaxiLang
// Source data model
model Movie {
   id: FilmId
   title: Title
}

// Target model for database
model Film {
   @Id
   filmId: FilmId
   title: Title
   reviewScore: ReviewScore  // Additional field not in source
}

service FilmDatabase {
   write operation saveFilm(Film):Film
}

// TaxiQL will automatically discover missing data
find { Movie[] }
call FilmDatabase::saveFilm
```

--------------------------------

### Define a Basic Service in Taxi

Source: https://taxilang.org/docs/language/services

Defines a service named CustomerApi with operations to get a customer by ID and list all customers. This is a fundamental way to describe data sources in Taxi.

```Taxi
service CustomerApi {
   // Get a customer by their ID
   operation getCustomer(CustomerId):Customer
   
   // List all customers
   operation listCustomers():Customer[]
}
```

--------------------------------

### Basic Extension Functions in Taxilang

Source: https://taxilang.org/docs/taxiql/functions

Extension functions provide a method-like syntax for operations on specific types, enhancing readability and discoverability. This example shows declaration and usage.

```Taxilang
// Declare extension function
declare extension function upperCase(String): String
declare extension function isActive(Customer): Boolean

// Usage as method calls
find { Customer } as {
   name: CustomerName.upperCase()
   active: Customer.isActive()
}
```

--------------------------------

### Taxi Function Declarations with Named Parameters

Source: https://taxilang.org/docs/taxiql/functions

Provides examples of declaring Taxi functions using named parameters, enhancing clarity for functions with multiple parameters, especially those of the same type.

```Taxi
declare function concat(first: String, second: String): String
declare function substring(
   text: String, 
   start: Int, 
   length: Int
): String
```

--------------------------------

### Enhance Protocol Buffers with taxi.dataType

Source: https://taxilang.org/docs/other-api-specs/working-with-other-api-specs

This example shows how to enhance Protocol Buffer messages with semantic types using the `taxi.dataType` extension. It annotates customer ID and email fields.

```protobuf
message Customer {
  optional string id = 1 [(taxi.dataType)="acme.CustomerId"];
  optional string email = 2 [(taxi.dataType)="acme.EmailAddress"];
}
```

--------------------------------

### Calculate Final Price Considering Discount Rate Discovery

Source: https://taxilang.org/docs/taxiql/expressions-traversal

This example illustrates data discovery during expression evaluation. The 'DiscountRate' is not directly on the 'Order' model but is discovered and used to calculate the 'finalPrice'.

```Taxi
model Order {
   basePrice : Price
   customerId : CustomerId
}

// DiscountRate not on Order, will be discovered
find { Order[] } as {
   price : Price
   finalPrice : Decimal = Price * (1 - DiscountRate)
}[]
```

--------------------------------

### Generic Functions in Taxi

Source: https://taxilang.org/docs/taxiql/functions

Explains generic functions in Taxi, providing type safety across different data types. Includes examples of generic function declarations, extension functions, and their usage.

```taxi
// Generic function declaration
declare function <T> firstOrNull(T[]): T?
declare function <T, R> transform(T, transformer: (T) -> R): R

// Generic extension function
declare extension function <T> isEmpty(T[]): Boolean

// Usage maintains type safety
type FirstCustomer = firstOrNull(Customer[])  // Returns Customer?
type Names = transform(Customer[], (Customer[]) -> String[])  // Returns String[]
```

--------------------------------

### Fold Collection to Single Value - TaxiLang

Source: https://taxilang.org/docs/language/stdlib

Iterates over a collection, applying a callback function to accumulate a single result. It starts with an initial value and combines each element with the accumulator. Example demonstrates calculating a weighted average.

```TaxiLang
declare extension function <T,A> fold(collection: T[], initial: A, callback: (T,A) -> A):A

// Example:
// model Entry {
//    weight:Weight inherits Int
//    score:Score inherits Int
// }
//
// type WeightedAverage by (Entry[]) -> Entry[].fold(0, (Entry, Int) -> Int + (Weight*Score))
```

--------------------------------

### Nested Function Calls in Taxi

Source: https://taxilang.org/docs/taxiql/functions

Illustrates nested function calls for formatting data in Taxi. Examples show both type-based and variable-based approaches for constructing formatted strings from customer data.

```taxi
// Type-based approach
function formatCustomerSummary(Customer): String ->
   concat(
      Customer::FirstName.upperCase(),
      " ",
      Customer::LastName.upperCase(),
      " (",
      Customer::EmailAddress.lowerCase(),
      ")"
   )

// With variable for readability
function formatCustomerSummary(customer: Customer): String ->
   concat(
      customer::FirstName.upperCase(),
      " ",
      customer::LastName.upperCase(),
      " (",
      customer::EmailAddress.lowerCase(),
      ")"
   )
```

--------------------------------

### Initialize a New Taxi Project

Source: https://taxilang.org/docs/taxi-cli/taxi-cli-intro

Commands to create a new Taxi project, including the necessary `taxi.conf` file and directory structure. It prompts the user for project details.

```shell
$ taxi init

mkdir hello-world
cd hello-world
taxi init
```

--------------------------------

### Automatic Data Enrichment in TaxiQL

Source: https://taxilang.org/docs/taxiql/projections

Shows how TaxiQL automatically discovers and calls services to populate fields not present in the source data, enabling rich data enrichment without manual service orchestration. This example demonstrates automatic discovery via a customerId.

```TaxiQL
model Purchase {
   customerId : CustomerId
   amount : Amount
}

model Customer {
   @Id customerId : CustomerId
   name : CustomerName
}

service CustomerService {
   operation findCustomer(CustomerId): Customer
}

// CustomerName automatically discovered via customerId
find { Purchase[] } as {
   amount : Amount
   customerName : CustomerName
}[]
```

--------------------------------

### Launch Orbital (TaxiQL Query Engine)

Source: https://taxilang.org/docs/taxi-cli/taxi-cli-intro

Command to launch a local instance of Orbital, a TaxiQL query engine, with live updates for the Taxi project. Downloads and runs a Docker Compose configuration.

```shell
taxi orbital

taxi orbital -v 0.14.0
```

--------------------------------

### Field Shorthand Selection in TaxiQL

Source: https://taxilang.org/docs/taxiql/projections

This example demonstrates the field shorthand syntax in TaxiQL for selecting specific fields from a source `Order` model without changing their types. It's a concise way to rename or simply include fields, with types being automatically inferred from the source. This requires a pre-defined `model` for the source.

```TaxiQL
model Order {
   id: OrderId
   status: OrderStatus
   total: OrderTotal
}

find { Order[] } as {
   id        // Selects OrderId
   status    // Selects OrderStatus
}[]
```

--------------------------------

### Single vs. Batch Mutations in TaxiLang

Source: https://taxilang.org/docs/taxiql/mutations

This example differentiates between single and batch mutation operations in TaxiLang based on their input types. 'saveSingle' processes one film at a time, while 'saveBatch' expects an array of films for efficient bulk processing.

```TaxiLang
service FilmService {
   // Processes one film at a time
   write operation saveSingle(Film):Film
   
   // Processes films in batches
   write operation saveBatch(Film[]):Film[]
}
```

--------------------------------

### Pipeline Pattern for Function Composition in Taxi

Source: https://taxilang.org/docs/taxiql/functions

Showcases the pipeline pattern in Taxi for chaining operations, including simple string manipulations and complex filtering/mapping sequences. Examples use type references and variable names for readability.

```taxi
// Chained operations with type references
function processCustomerName(String): String ->
   String.trim().lowerCase().capitalizeFirst()

// With filtering and transformation
function getActiveCustomerEmails(Customer[]): EmailAddress[] ->
   Customer[]
      .filter((Customer) -> Customer::IsActive == true)
      .filter((Customer) -> Customer::HasEmail == true)
      .map((Customer) -> Customer::EmailAddress)

// Same logic with variable names for readability
function getActiveCustomerEmails(customers: Customer[]): EmailAddress[] ->
   customers
      .filter((c: Customer) -> c::IsActive == true)
      .filter((c: Customer) -> c::HasEmail == true)
      .map((c: Customer) -> c::EmailAddress)
```

--------------------------------

### Define a REST API Service with HttpService in Taxi

Source: https://taxilang.org/docs/language/services

Defines a RESTful service CustomerApi using the @HttpService annotation. It specifies the base URL and defines operations for listing and getting customers, mapping them to HTTP GET requests.

```Taxi
@HttpService(baseUrl = "https://api.example.com/v1")
service CustomerApi {
   // Resolves to GET https://api.example.com/v1/customers
   @HttpOperation(method = "GET", url = "/customers")
   operation listCustomers():Customer[]
   
   // Resolves to GET https://api.example.com/v1/customers/{id}
   @HttpOperation(method = "GET", url = "/customers/{id}")
   operation getCustomer( @PathVariable(name = "id") id: CustomerId ):Customer
}
```

--------------------------------

### Sample Configuration for Taxi Kotlin Plugin with Maven

Source: https://taxilang.org/docs/taxi-cli/kotlin-plugin

This configuration demonstrates how to set up the Taxi Kotlin plugin with Maven integration. It specifies Maven coordinates, custom repositories, and distribution management for publishing artifacts. This allows for the generation of a `pom.xml` file that can be used to build and deploy the generated Kotlin code as a Maven artifact.

```yaml
name: taxi/maven-sample
version: 0.3.0
sourceRoot: src/
plugins: {
   taxi/kotlin: {
      maven: {
         groupId: "lang.taxi"
         artifactId: "parent"
         repositories: [
            {
               id: "internal-repo"
               url: "https://newcorp.nexus.com"
               snapshots: true
            }
         ]
         distributionManagement: {
            id: "some-internal-repo"
            url: "https://our-internal-repo"
         }
      }
   }
}

```

--------------------------------

### Publish Taxi Project

Source: https://taxilang.org/docs/taxi-cli/taxi-cli-intro

Command to publish the current Taxi project to a configured repository. It creates a zip archive containing `taxi.conf` and source files.

```shell
$ taxi publish
```

--------------------------------

### Get Current DateTime - TaxiLang

Source: https://taxilang.org/docs/language/stdlib

Retrieves the current date and time. Returns a value of type `DateTime`.

```TaxiLang
declare function currentDateTime():DateTime
```

--------------------------------

### Build Taxi Project

Source: https://taxilang.org/docs/taxi-cli/taxi-cli-intro

Command to compile the Taxi project and invoke language generators. This command validates the syntax of Taxi code and applies configured plugins.

```shell
taxi build
```

--------------------------------

### Get Current Time - TaxiLang

Source: https://taxilang.org/docs/language/stdlib

Retrieves the current time without the date component. Returns a value of type `Time`.

```TaxiLang
declare function currentTime():Time
```

--------------------------------

### Get Current Date - TaxiLang

Source: https://taxilang.org/docs/language/stdlib

Retrieves the current date without the time component. Returns a value of type `Date`.

```TaxiLang
declare function currentDate():Date
```

--------------------------------

### Get Collection Size - TaxiLang

Source: https://taxilang.org/docs/language/stdlib

Returns the number of elements within a given collection. This is a fundamental operation for understanding collection size.

```TaxiLang
declare extension function <T> size(collection:T[]):Int
```

--------------------------------

### Basic TaxiQL Projection Syntax

Source: https://taxilang.org/docs/taxiql/projections

This snippet demonstrates the fundamental syntax for creating a projection in TaxiQL. It shows how to specify a data source and define the target structure for the transformed data. No external dependencies are required beyond the TaxiQL language itself.

```TaxiQL
find { Source } as { /* .. target structure.. */}
```

--------------------------------

### Project File Organization for Semantic Types (TaxiLang)

Source: https://taxilang.org/docs/language/adopting-semantic-types

Illustrates a recommended project structure for separating shared semantic types from system-specific models. This promotes modularity and maintainability, especially as the taxonomy grows.

```TaxiLang
src/
  types/           # Shared semantic types (your taxonomy)
    customer.taxi
    order.taxi
  models/          # System-specific models
    service-a/
      customer-model.taxi
      service-definitions.taxi
    service-b/
      customer.api.taxi # A REST API exposing customer details. Has both model and services defined
```

--------------------------------

### Get Current Instant - TaxiLang

Source: https://taxilang.org/docs/language/stdlib

Retrieves the current instant in time, typically representing a point on the timeline. Returns a value of type `Instant`.

```TaxiLang
declare function now():Instant
```

--------------------------------

### Applying Annotations to Services and Operations in Taxilang

Source: https://taxilang.org/docs/language/annotations

Illustrates the application of annotations to service and operation definitions in Taxilang. This includes annotations for HTTP configuration, rate limiting, caching, documentation, validation, and auditing.

```Taxilang
@HttpService(baseUrl = "https://api.example.com")
@RateLimit(requestsPerMinute = 100)
service CustomerService {
    
    @HttpOperation(method = "GET", url = "/customers/{id}")
    @Cacheable(ttl = 300)
    @Documentation(description = "Retrieve customer by ID")
    operation getCustomer(id: CustomerId): Customer
    
    @HttpOperation(method = "POST", url = "/customers")
    @Validation(required = true)
    @Audit(level = "HIGH")
    operation createCustomer(customer: Customer): CustomerId
}
```

--------------------------------

### Configure Kotlin Plugin with Maven Sample

Source: https://taxilang.org/docs/taxi-cli/plugins

This YAML configuration demonstrates how to set up the 'taxi/kotlin' plugin with specific Maven configurations. It includes settings for groupId, artifactId, and custom repositories for dependency management.

```yaml
name: taxi/maven-sample
version: 0.3.0
sourceRoot: src/
plugins: {
   taxi/kotlin: {
      maven: {
         groupId: "lang.taxi"
         artifactId: "parent"
         repositories: [
            {
               id: "internal-repo"
               url: "https://newcorp.nexus.com"
               snapshots: true
            }
         ]
         distributionManagement: {
            id: "some-internal-repo"
            url: "https://our-internal-repo"
         }
      }
   }
}
```

--------------------------------

### Mid Substring Extraction in Taxi StdLib

Source: https://taxilang.org/docs/language/stdlib

Extracts a portion of a string between a start index (inclusive) and an end index (exclusive). This is an extension function for strings.

```Taxi
declare extension function mid(source: String,startIndex: Int,endIndex: Int):String
```

--------------------------------

### Get Enum Value by Name - TaxiLang

Source: https://taxilang.org/docs/language/stdlib

Retrieves an enum value corresponding to a given enum type and name. Returns the enum value of type `T`.

```TaxiLang
declare extension function <T> enumForName(enumType: lang.taxi.Type<T>, enumName: String): T
```

--------------------------------

### Running Nexus Docker Image

Source: https://taxilang.org/docs/packages/publishing

This command demonstrates how to run a Sonatype Nexus 3 Docker container. It maps the Nexus data directory and exposes the default Nexus port, allowing for a local Nexus instance to be used as an artifact repository.

```bash
$ mkdir /some/dir/nexus-data && chown -R 200 /some/dir/nexus-data
$ docker run -d -p 8081:8081 --name nexus -v /some/dir/nexus-data:/nexus-data sonatype/nexus3
```

--------------------------------

### Dynamic Categorization Using Conditional Expressions

Source: https://taxilang.org/docs/taxiql/expressions-traversal

An example of using a 'when' clause to create a 'CustomerSegment' expression type. This dynamically categorizes customers based on their 'LifetimeValue' and 'LastOrderDays'.

```Taxi
type CustomerSegment = when {
   LifetimeValue > 10000 && LastOrderDays < 30 -> "VIP Active"
   LifetimeValue > 10000 -> "VIP Dormant"  
   LastOrderDays < 90 -> "Regular Active"
   else -> "At Risk"
}
```

--------------------------------

### Substring Index in Taxi StdLib Strings

Source: https://taxilang.org/docs/language/stdlib

Finds the starting index of a substring within a source string. Returns -1 if the substring is not found. This is an extension function for strings.

```Taxi
declare extension function indexOf(source:String, valueToSearchFor:String):Int
```

--------------------------------

### Nested Enrichment Pattern in TaxiQL

Source: https://taxilang.org/docs/taxiql/projections

Demonstrates a nested enrichment pattern in TaxiQL, where data within a collection is further enriched. This example enriches invoice items with product and supplier details.

```TaxiQL
find { Invoice[] } as {
   invoiceNumber : InvoiceNumber
   items : InvoiceItem[] as {
      description : ItemDescription
      // Enrich each item with product details
      productCategory : ProductCategory
      supplier : SupplierName
   }[]
}[]
```

--------------------------------

### Applying Annotations to Models in Taxilang

Source: https://taxilang.org/docs/language/annotations

Demonstrates applying annotations to model definitions in Taxilang. This covers applying documentation and serialization annotations to the model itself, and validation/documentation to its fields.

```Taxilang
@Documentation(description = "Core customer data structure")
@JsonSerializable(camelCase = true)
model Customer {
    @Validation(minLength = 1)
    id: CustomerId
    
    @Documentation(description = "Customer's display name")
    name: CustomerName
    
    @Internal
    internalScore: Int?
}
```

--------------------------------

### TaxiLang: Lenient Enum with Special Characters

Source: https://taxilang.org/docs/language/basic-types

Shows an example of a lenient enum in TaxiLang where member values contain special characters, demonstrating flexible matching.

```TaxiLang
lenient enum DayCountConvention {
   ACT_360("ACT/360")
}
```

--------------------------------

### GitHub and GitLab Shorthand for Taxi Dependencies

Source: https://taxilang.org/docs/packages/publishing

This snippet illustrates the shorthand notation for declaring dependencies from GitHub and GitLab in the `taxi.conf` file. It simplifies the dependency declaration by allowing the use of `github:` or `gitlab:` prefixes followed by the organization and project name, optionally including a tag or branch.

```taxi.conf
dependencies: {
    // Fetch from a github repository, at a specific branch / tag
    "com.orbitalhq/core" : "github:orbitalapi/orbital-core-taxi#0.34.0"
   
    // Fetch from a gitlab repository (at https://gitlab.com) on the default branch
    "org.test/dependencyA" : "gitlab:taxi-lang/test-project-a"
}
```

--------------------------------

### Basic Taxi Syntax in OpenAPI

Source: https://taxilang.org/docs/other-api-specs/open-api

Demonstrates the basic syntax for adding Taxi metadata using `x-taxi-type` extensions within an OpenAPI specification.

```APIDOC
## Basic Syntax

Taxi metadata is added using `x-taxi-type` extensions in your OpenAPI spec:

```yaml
x-taxi-type:
  name: com.acme.MyType    # The semantic type name
  create: false            # Optional flag to control type creation
```
```

--------------------------------

### Basic Projections in Taxilang

Source: https://taxilang.org/docs/taxiql/querying

Shows how to use projections to transform and enrich data. This includes projecting to a different structure, projecting to a named type, and selecting specific fields from a dataset.

```Taxilang
// Project to a different structure
find { Movie[] } as {
   title : MovieTitle
   director : DirectorName
   rating : RottenTomatoesScore
}[]
```

```Taxilang
// Project to a named type
find { Book[] } as BookAndAuthor[]
```

```Taxilang
// Select specific fields
find { Order[] } as {
   id        // Field shorthand
   status    
   total     
}[]
```

--------------------------------

### Nested Lambda Expressions for Filtering Customers

Source: https://taxilang.org/docs/taxiql/expressions-traversal

Provides an example of nested lambda expressions to filter a collection of 'Customer' objects based on multiple criteria, including account status and premium membership.

```Taxi
// Find customers with active premium accounts
type PremiumActiveCustomers = 
   (Customer[]) -> Customer[]
      .filter((HasAccount) -> HasAccount == true)
      .filter((Account) -> Account::Status == "Premium")
      .filter((Account) -> Account::IsActive == true)
```

--------------------------------

### Define XML Schema with Taxi Annotations

Source: https://taxilang.org/docs/other-api-specs/working-with-other-api-specs

This example defines an XML schema using Taxi annotations. The `@Xml` annotation is used for the model, and `@XmlAttribute` specifies that the 'id' field should be an XML attribute.

```taxiql
@Xml
model CustomerImport {
   @XmlAttribute
   id: CustomerId
   email: EmailAddress
}
```

--------------------------------

### TaxiQL Organization Best Practice

Source: https://taxilang.org/docs/language/models

Demonstrates organizing related models and services together. Request and response models for a specific operation are grouped, followed by the service definition that uses them.

```TaxiQL
// Service-specific models together
model CreateOrderRequest {
    customerId: CustomerId
    items: OrderItem[]
}

model CreateOrderResponse {
    orderId: OrderId
    status: OrderStatus
}

// Service definition with its models
service OrderService {
    operation createOrder(CreateOrderRequest): CreateOrderResponse
}
```

--------------------------------

### Access Properties by Name in Taxi

Source: https://taxilang.org/docs/taxiql/querying

Demonstrates accessing data using property names with the dot-selector syntax. This method requires the exact data structure. It also shows how to mix property name access with type references.

```Taxi
model Customer {
address : Address
}
model Address {
houseNumber: HouseNumber inherits String
line1: AddressLine1 inherits String
postcode: PostCode inherits String
}

given {
// Note that the customer variable is named here.
customer: Customer = {
address: {
houseNumber: '5a',
line1: 'Semantic Ave',
postcode: 'SW2 4NN'
}
}}
find {
// Accessing a property by chaining property access
addressLine1: String = customer.address.line1
// mixing property name access with type references is also possible
postcode: customer.address::PostCode
}
```

--------------------------------

### Add Semantic Types to OpenAPI using x-taxi-type

Source: https://taxilang.org/docs/other-api-specs/working-with-other-api-specs

This snippet demonstrates how to add semantic types to OpenAPI specifications using the `x-taxi-type` extension. It shows an example of annotating a customer ID parameter.

```yaml
paths:
  /customers/{id}:
    get:
      parameters:
        - name: id
          schema:
            type: string
            x-taxi-type:
              name: acme.CustomerId
```

--------------------------------

### Get First Item from Collection - Taxi Stdlib

Source: https://taxilang.org/docs/language/stdlib

The `first` function returns the first item in an ordered collection. It throws an error if the collection is empty. This is useful for retrieving the earliest or most primary element.

```Taxi
declare extension function <T> first(collection: T[]):T
```

```Taxi
// Get the most recent transaction from a sorted list
find { account: Account } as {
   latestTransaction: account.transactions.first()
}
```

--------------------------------

### Declaring Taxi Project Dependencies

Source: https://taxilang.org/docs/packages/taxi-projects

Shows various ways to declare dependencies on other Taxi projects within the `taxi.conf` file, including fetching from package managers, specific Git branches/tags, and different Git providers.

```hocon
dependencies: { 
    // Fetch from a package manager, such as Nexus 
    "org/ProjectName" : 0.2.0 

    // Fetch from a github repository, at a specific branch / tag 
    "com.orbitalhq/core" : "github:orbitalapi/orbital-core-taxi#0.34.0" 
   
    // Fetch from a gitlab repository (at https://gitlab.com) on the default branch 
    "org.test/dependencyA" : "gitlab:taxi-lang/test-project-a" 

    // Fetch from a different git provider 
    "org.test/dependencyB" : "https://someGitProvider.com/taxi-lang/test-project-a.git" 

}
```

--------------------------------

### TaxiQL: Unambiguous Deep Traversal

Source: https://taxilang.org/docs/taxiql/querying

This snippet shows an example of deep traversal using 'Customer::AddressLine1' in TaxiQL. It highlights that the expression must resolve to exactly one field to avoid ambiguity and returning null.

```TaxiQL
// Finds an instance of AddressLine1 anywhere in a Customer model 
Customer::AddressLine1
```

--------------------------------

### TaxiQL Documenting Nullability Best Practice

Source: https://taxilang.org/docs/language/models

Shows how to document nullability in TaxiQL models using the `?` suffix for optional fields. This practice improves clarity on which fields are required and which are optional.

```TaxiQL
model User {
    // Required fields - core identity
    id: UserId
    email: EmailAddress
    
    // Optional fields - additional information
    middleName: MiddleName?
    phoneNumber: PhoneNumber?
}
```

--------------------------------

### TaxiQL Constructing Write Operation Inputs

Source: https://taxilang.org/docs/language/services

Demonstrates how TaxiQL automatically constructs operation inputs using available data from the query context, allowing for flexibility in 'given' or 'find' statements without exact parameter matching. The engine matches data types from previous statements to the operation's parameter types.

```TaxiQL
// Operation signature
write operation updatePerson(Person):Person

query UpdatePersonName {
   // TaxiQL will construct a Person object using available fields
   given {
      id: PersonId = "123"
      name: PersonName = "Alice"
   }
   call PersonService::updatePerson
}
```

--------------------------------

### Taxi Annotations with Object Literals for Parameters

Source: https://taxilang.org/docs/language/annotations

Demonstrates how to use object literal syntax within annotations to pass structured data as parameters. This is useful for providing complex configuration or error details.

```Taxi
model ValidationError {
    code: Int
    message: String
    field: String?
}

annotation Validate {
    error: ValidationError
    enabled: Boolean = true
}

// Using object literal syntax
@Validate(error = {
    code = 1001,
    message = "Invalid email format",
    field = "email"
})
type EmailAddress inherits String
```

--------------------------------

### Combine Traversal and Expression Types for Data Discovery

Source: https://taxilang.org/docs/taxiql/expressions-traversal

This snippet shows how expression types can be traversed to access nested data. It includes an example of defining 'PrimaryEmail' by traversing 'PrimaryContact' and using it within a query.

```Taxi
// Expression type using traversal
type PrimaryEmail inherits EmailAddress = 
   PrimaryContact::EmailAddress

// In a query
find { Case } as {
   // Combines traversal with expression types
   mainContactEmail: PrimaryApplicant::ActiveAddress::EmailAddress
   // Multiple levels of expression types
   primaryPhone: PrimaryContact::PreferredPhone
}
```

--------------------------------

### Filter and Transform Collections Using Expression Types

Source: https://taxilang.org/docs/taxiql/expressions-traversal

Demonstrates creating expression types to filter and transform collections of 'Address' objects. It includes examples for filtering to a single item, a collection, and using negation.

```Taxi
type IsActive inherits Boolean
type IsPrimary inherits Boolean

// Filter to single item
type ActiveAddress inherits Address = 
   (Address[]) -> Address[].single((IsActive) -> IsActive == true)

// Filter to collection
type ActiveAddresses inherits Address[] = 
   (Address[]) -> Address[].filter((IsActive) -> IsActive == true)

// With negation
type InactiveAddresses inherits Address[] = 
   (Address[]) -> Address[].filter((IsActive) -> IsActive != true)
```

--------------------------------

### Simplified PublishToRepository Configuration for TaxiLang

Source: https://taxilang.org/docs/packages/publishing

A streamlined configuration for publishing to a Nexus repository, often used when credentials are managed separately. It specifies the repository URL, a name for credential lookup, and the Nexus repository name.

```taxi.conf
publishToRepository: {
   url: "http://localhost:8081/"
   name : "nexus"
   settings: {
      repositoryName : taxi
   }
}
```

--------------------------------

### Transformation: Object to Object (TaxiQL)

Source: https://taxilang.org/docs/taxiql/projections

Illustrates transforming a single input object into a single output object (A as B). This is used for direct type conversions.

```TaxiQL
find { Actor } as FamousActor
```

```TaxiQL
find { Film } as {
  starring : Actor as FamousActor
}
```

--------------------------------

### Taxi Annotations with Object and Enum Fields

Source: https://taxilang.org/docs/language/annotations

Illustrates defining annotations that include complex field types like enums, arrays, and nested objects, along with an example of using an annotation with an object parameter.

```Taxi
enum Severity {
    LOW, MEDIUM, HIGH, CRITICAL
}

model ErrorDetails {
    code: Int
    description: String
    timestamp: String?
}

annotation Alert {
    message: String
    severity: Severity
    tags: String[]
    details: ErrorDetails?  // Object field
}

annotation Metadata {
    alert: Alert?
    internal: Boolean = false
}

// Usage with object parameter
@Alert(
    message = "Validation failed", 
    severity = Severity.HIGH,
    tags = ["validation", "input"],
    details = {
        code = 1001,
        description = "Email format is invalid",
        timestamp = "2024-01-15T10:30:00Z"
    }
)
type EmailAddress inherits String
```

--------------------------------

### Define HTTP Operations in Taxi

Source: https://taxilang.org/docs/language/services

Defines various HTTP operations (GET, POST, PUT) for an OrderApi service. It demonstrates how to map operations to HTTP methods, URLs, path variables, and request bodies.

```Taxi
service OrderApi {
   // GET request
   @HttpOperation(method = "GET", url = "/orders")
   operation listOrders():Order[]
   
   // POST with request body
   @HttpOperation(method = "POST", url = "/orders")
   operation createOrder( @HttpRequestBody order: CreateOrderRequest ):Order
   
   // PUT with path parameter
   @HttpOperation(method = "PUT", url = "/orders/{orderId}/status")
   operation updateStatus(
      @PathVariable(name = "orderId") id: OrderId,
      @HttpRequestBody status: OrderStatus
   ):Order
}
```

--------------------------------

### Create and Filter Lists with taxi.stdlib.listOf

Source: https://taxilang.org/docs/language/stdlib

The `listOf` function creates an array from provided values, useful for inline collections. It can be used to filter data, as demonstrated in the example where orders are filtered based on a list of valid statuses.

```TaxiLang
model Order {
id: String
status: String
}

given {
orders: Order[] = [
{ id: 'order-1', status: 'PENDING' },
{ id: 'order-2', status: 'SHIPPED' },
{ id: 'order-3', status: 'CANCELED' }
]
}
find {
validOrders: Order[] = orders.filter((order:Order) ->
listOf('PENDING', 'PROCESSING', 'SHIPPED', 'DELIVERED').contains(order.status)
)
invalidOrders: Order[] = orders.filter((order:Order) ->
listOf('PENDING', 'PROCESSING', 'SHIPPED', 'DELIVERED').contains(order.status) == false
)
}
```

--------------------------------

### Configure Nexus Repository for Publishing TaxiLang Projects

Source: https://taxilang.org/docs/packages/publishing

Specifies the Nexus repository details for publishing TaxiLang projects. Includes the repository name for credentials lookup, the Nexus base URL, and the specific repository name within Nexus.

```taxi.conf
publishToRepository: {
   // This name is used to look up credentials for auth
   name: "my-corporate-nexus"
   // The base url of the nexus
   url: "http://localhost:8081/"
   settings: {
      // The name you assigned to your repository when creating it in nexus
      repositoryName: taxi-on-nexus
   }
}
```

--------------------------------

### Declare Basic Taxi Functions

Source: https://taxilang.org/docs/taxiql/functions

Demonstrates basic function declarations in Taxi, including single and multiple type-based parameters, and optional variable names for improved readability.

```Taxi
// Basic function - parameter defined by type
function upperTrim(String): String -> String.trim().upperCase()

// Multiple parameters by type
function concat(String, String): String

// Optional variable names for readability
function upperTrim(text: String): String -> text.trim().upperCase()
function concat(first: String, second: String): String
```

--------------------------------

### Define CSV Schema with Taxi Annotations

Source: https://taxilang.org/docs/other-api-specs/working-with-other-api-specs

This example defines a CSV schema using Taxi annotations. The `@Csv` annotation specifies the delimiter, and the `model` defines fields with semantic types like `CustomerId` and `EmailAddress`.

```taxiql
@Csv(delimiter = "|")
model CustomerExport {
   id: CustomerId
   email: EmailAddress
}
```

--------------------------------

### Get Last Item using last

Source: https://taxilang.org/docs/language/stdlib

The `last` function retrieves the final element from a collection. It will throw an error if the collection is empty. This is particularly useful for fetching the most recent or oldest item in a sorted list, such as transactions.

```Taxi
model Transaction {
  date: String
  amount: Decimal
  description: String
}

model Account {
  accountNumber: String
  transactions: Transaction[] // Assumed to be in descending date order
}

given {
  account: Account = {
    accountNumber: 'ACC-12345',
    transactions: [
      { date: '2023-05-01', amount: 150.00, description: 'Grocery Store' },
      { date: '2023-04-28', amount: 45.99, description: 'Online Shop' },
      { date: '2023-04-25', amount: 20.00, description: 'Transfer' }
    ]
  }
}
find {
  accountNumber: account.accountNumber
  mostRecentTransaction: Transaction = account.transactions.first() // Example uses 'first()', but 'last()' is documented.
  // To demonstrate 'last':
  oldestTransaction: Transaction = account.transactions.last()
}
```

--------------------------------

### Multiple Parameter Lambdas in Taxi

Source: https://taxilang.org/docs/taxiql/functions

Demonstrates the use of lambdas with multiple parameters in Taxi for operations like 'reduce'. It shows type-based and variable-named parameter definitions for clarity and flexibility.

```taxi
declare function reduce<T, R>(
   items: T[], 
   initial: R, 
   reducer: (R, T) -> R
): R

// Type-based parameters
type TotalValue = reduce(Order[], 0, (Decimal, Order) -> Decimal + Order::Amount)

// With variable names
type TotalValue = reduce(Order[], 0, (total: Decimal, order: Order) -> total + order::Amount)
```
Tokens:
Raw