DOCSEARCHbyAlgolia
Submit Docs

Publicodes API Documentation

website·Indexed 33 days ago

https://publi.codes

Technical reference for the Publicodes ecosystem, including the core engine, @publicodes/tools for compilation and migration, @publicodes/react-ui for user interface components, and @publicodes/forms for dynamic field computation.

Tokens
43.5K
Snippets
261
Records
350
Agent score
69%

What's inside Publicodes

  1. Overview of @publicodes/rest-api

    @publicodes/rest-api is a package that allows you to create an OpenAPI 3.0 compliant REST API from Publicodes rules. It is implemented as Koa middleware and provides the following default endpoints:

    • POST /evaluate: Evaluate one or more expressions given a specific situation.
    • GET /rules: Retrieve a list of all defined rules.
    • GET /rules/{rule}: Retrieve a specific rule by its identifier.

  2. Overview of Publicodes for business logic modeling

    Publicodes is a low-code language designed to model complex business domains by breaking them down into simple, elementary rules. It is specifically designed for 'Rules as Code' applications, allowing laws and regulations to be transposed into code that is readable by both developers and domain experts. The system decouples business logic from application code to improve maintainability and testability, and uses a JavaScript interpreter that can be embedded directly in the browser to reduce network calls.

  3. Publicodes Developer Tooling and Ecosystem

    Publicodes provides several tools to assist developers in writing and managing rules:

    • VSCode Extension: Provides syntax highlighting and autocompletion for Publicodes rules.
    • Language Server: A published language server that allows developers to port Publicodes support to other editors.
    • @publicodes/tools: A set of utility tools for the language (currently being transitioned into a dedicated CLI for easier access).

  4. Understand and use mechanisms in Publicodes

    Mechanisms are predefined operations (similar to base language functions) used to calculate a value based on other values. They are invoked within a rule by specifying the mechanism name followed by its parameters.

  5. Publicodes V2 Architectural Overview

    Publicodes V2 transitions from an interpreted language to a compiled language to eliminate performance bottlenecks and improve execution reliability. The new architecture consists of three main stages: 1) An OCaml-based compiler that analyzes and transforms rules, 2) The generation of a minimal and optimized evaluation tree, and 3) A lightweight runtime dedicated solely to execution.

  6. New Language Features and Concepts in Publicodes V2

    Publicodes V2 introduces several new concepts and improvements to the rule-writing process:

    • public attribute: Used to specify which rules should be exported from a model.
    • Parameters: The previous concept of 'missing variables' (missingVariable) is being replaced by a more standard 'parameters' concept.
    • Native TypeScript Integration: Allows developers to use Publicodes models without needing deep knowledge of the internal language.
    • Static Verification: Errors such as type/unit inconsistencies and cycles are detected during the rule-writing phase rather than at runtime.

  7. Core features of @publicodes/tools

    @publicodes/tools provides several key capabilities for Publicodes development:

    • Compilation: Converts .publicodes files into JSON models and TypeScript types.
    • Rule Imports: Supports importing rules from NPM packages using the importer! syntax.
    • Optimization: Includes a constant folding pass to optimize models.
    • Migration: Provides utilities for migrating between different Publicodes versions.

  9. Publicodes design philosophy and goals

    Publicodes is designed to store business logic (such as legislative rules, tax brackets, and social contribution calculations) as declarative data in a readable rule base. Unlike traditional numerical calculation engines, Publicodes aims to create a documented, explorable, and calculable base of legislation where the user interface (forms) is automatically generated from the rules, rather than built manually.

  10. Manipulate Publicodes rule names using the utils namespace

    The utils namespace (marked as Experimental) provides a collection of functions to handle dottedName strings, manage rule hierarchies, and analyze dependencies within Publicodes rules.

  11. Implement testing strategies for public models

    Since public models often serve as the reference they are trying to build, diverse testing strategies are required:

    1. Typical Use Cases: Store calculation results from standard scenarios to detect regressions after changes.
    2. Unit Testing: Test the underlying framework's calculation functions (e.g., sums, multiplications, scales, emission factor tables).
    3. Formula Homogeneity: Verify that typed variables (e.g., hours, kgCO2e/hour) result in the correct final unit of measurement.

  12. Define nested rules using the 'avec' keyword

    In Publicodes, you can define child rules to organize variables used by a parent rule. While you can use dot notation (e.g., parent . child), the avec keyword allows you to define these child rules directly within the parent rule's body for cleaner syntax.
    prix final:
   valeur: prix de base * (100% - réduction)
   avec:
     prix de base: 157 €
     réduction: 20%