tessl/npm-notion-types

TypeScript types for core Notion data structures.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Formulas

Name: tessl/npm-notion-types
Author: tessl

Complete type definitions for Notion's formula language including all operators, functions, and value types. Supports logic, math, text, and date operations with full type safety.

Capabilities

Base Formula Interface

All formula components inherit from the BaseFormula interface.

/**
 * Base properties for all formula components
 */
interface BaseFormula {
  /** Formula component type */
  type: FormulaType;
  /** Expected result type */
  result_type: FormulaResultType;
}

Formula Types

/**
 * Types of formula components
 */
type FormulaType =
  | 'constant'   // Constant values
  | 'property'   // Property references
  | 'operator'   // Mathematical/logical operators
  | 'function'   // Function calls
  | 'symbol';    // Named symbols

/**
 * Union of all formula component types
 */
type Formula =
  | FunctionFormula
  | OperatorFormula
  | ConstantFormula
  | PropertyFormula
  | SymbolFormula;

Value and Result Types

/**
 * Built-in constants
 */
type FormulaConstantType = 'e' | 'false' | 'true' | 'pi';

/**
 * Value types in formulas
 */
type FormulaValueType =
  | 'string'
  | 'number'
  | 'boolean'
  | 'date'
  | FormulaConstantType;

/**
 * Possible formula result values
 */
type FormulaResult = string | number | boolean | Date;

/**
 * Formula result type categories
 */
type FormulaResultType =
  | 'text'       // Text result
  | 'number'     // Numeric result
  | 'boolean'    // Boolean result
  | 'date'       // Date result
  | 'checkbox';  // Checkbox result

Operators

/**
 * Mathematical and logical operators
 */
type FormulaOperatorType =
  // Arithmetic
  | '-'    // Subtraction
  | '*'    // Multiplication
  | '%'    // Modulo
  | '/'    // Division
  | '+'    // Addition
  
  // Comparison
  | '!='   // Not equal
  | '<='   // Less than or equal
  | '=='   // Equal
  | '>'    // Greater than
  | '<'    // Less than
  | '>=';  // Greater than or equal

Functions

/**
 * Available formula functions
 */
type FormulaFunctionType =
  // Logic functions
  | 'and'        // Logical AND
  | 'empty'      // Check if empty
  | 'equal'      // Equality check
  | 'if'         // Conditional
  | 'larger'     // Greater than
  | 'largerEq'   // Greater than or equal
  | 'not'        // Logical NOT
  | 'or'         // Logical OR
  | 'smaller'    // Less than
  | 'smallerEq'  // Less than or equal
  | 'unequal'    // Not equal
  
  // Numeric functions
  | 'abs'        // Absolute value
  | 'add'        // Addition
  | 'cbrt'       // Cube root
  | 'ceil'       // Ceiling
  | 'divide'     // Division
  | 'exp'        // Exponential
  | 'floor'      // Floor
  | 'ln'         // Natural logarithm
  | 'log10'      // Base-10 logarithm
  | 'log2'       // Base-2 logarithm
  | 'max'        // Maximum
  | 'min'        // Minimum
  | 'mod'        // Modulo
  | 'multiply'   // Multiplication
  | 'pow'        // Power
  | 'round'      // Round
  | 'sign'       // Sign
  | 'sqrt'       // Square root
  | 'subtract'   // Subtraction
  | 'toNumber'   // Convert to number
  | 'unaryMinus' // Unary minus
  | 'unaryPlus'  // Unary plus
  
  // Text functions
  | 'concat'     // Concatenate strings
  | 'contains'   // Check if contains
  | 'format'     // Format value
  | 'join'       // Join array
  | 'length'     // String length
  | 'replace'    // Replace text
  | 'replaceAll'// Replace all occurrences
  | 'slice'      // String slice
  | 'test'       // Test regex
  
  // Date & time functions
  | 'date'        // Create date
  | 'dateAdd'     // Add to date
  | 'dateBetween' // Date difference
  | 'dateSubtract'// Subtract from date
  | 'day'         // Get day
  | 'end'         // End of range
  | 'formatDate'  // Format date
  | 'fromTimestamp'// From timestamp
  | 'hour'        // Get hour
  | 'minute'      // Get minute
  | 'month'       // Get month
  | 'now'         // Current time
  | 'start'       // Start of range
  | 'timestamp'   // Get timestamp
  | 'year';       // Get year

Specific Formula Types

/**
 * Constant value in formula
 */
interface ConstantFormula extends BaseFormula {
  type: 'constant';
  /** Constant value */
  value: any;
  /** Value type */
  value_type: FormulaValueType;
}

/**
 * Property reference in formula
 */
interface PropertyFormula extends BaseFormula {
  type: 'property';
  /** Referenced property ID */
  id: string;
  /** Property name */
  name: string;
}

/**
 * Named symbol in formula
 */
interface SymbolFormula extends BaseFormula {
  type: 'symbol';
  /** Symbol name */
  name: string;
}

/**
 * Function call in formula
 */
interface FunctionFormula extends BaseFormula {
  type: 'function';
  /** Function name */
  name: FormulaFunctionType;
  /** Function arguments */
  args: Array<Formula>;
}

/**
 * Operator expression in formula
 */
interface OperatorFormula extends BaseFormula {
  type: 'operator';
  /** Operator symbol */
  operator: FormulaOperatorType;
  /** Operator function name */
  name: FormulaFunctionType;
  /** Operands */
  args: Array<Formula>;
}

Usage Examples:

import { 
  Formula,
  FunctionFormula,
  PropertyFormula,
  ConstantFormula,
  FormulaFunctionType,
  FormulaResult 
} from "notion-types";

// Create a property reference
const nameProperty: PropertyFormula = {
  type: 'property',
  result_type: 'text',
  id: 'title',
  name: 'Name'
};

// Create a constant
const numberConstant: ConstantFormula = {
  type: 'constant',
  result_type: 'number',
  value: 42,
  value_type: 'number'
};

// Create a function that concatenates name with a greeting
const greetingFormula: FunctionFormula = {
  type: 'function',
  result_type: 'text',
  name: 'concat',
  args: [
    {
      type: 'constant',
      result_type: 'text',
      value: 'Hello, ',
      value_type: 'string'
    },
    nameProperty,
    {
      type: 'constant',
      result_type: 'text',
      value: '!',
      value_type: 'string'
    }
  ]
};

// Create a conditional formula
const statusFormula: FunctionFormula = {
  type: 'function',
  result_type: 'text',
  name: 'if',
  args: [
    {
      type: 'function',
      result_type: 'boolean',
      name: 'larger',
      args: [
        {
          type: 'property',
          result_type: 'number',
          id: 'age_prop',
          name: 'Age'
        },
        {
          type: 'constant',
          result_type: 'number',
          value: 18,
          value_type: 'number'
        }
      ]
    },
    {
      type: 'constant',
      result_type: 'text',
      value: 'Adult',
      value_type: 'string'
    },
    {
      type: 'constant',
      result_type: 'text',
      value: 'Minor',
      value_type: 'string'
    }
  ]
};

// Math formula: pow(age, 2) + 10
const mathFormula: FunctionFormula = {
  type: 'function',
  result_type: 'number',
  name: 'add',
  args: [
    {
      type: 'function',
      result_type: 'number',
      name: 'pow',
      args: [
        {
          type: 'property',
          result_type: 'number',
          id: 'age_prop',
          name: 'Age'
        },
        {
          type: 'constant',  
          result_type: 'number',
          value: 2,
          value_type: 'number'
        }
      ]
    },
    {
      type: 'constant',
      result_type: 'number', 
      value: 10,
      value_type: 'number'
    }
  ]
};

// Date formula: dateAdd(now(), 30, "days")
const futureDate: FunctionFormula = {
  type: 'function',
  result_type: 'date',
  name: 'dateAdd',
  args: [
    {
      type: 'function',
      result_type: 'date',
      name: 'now',
      args: []
    },
    {
      type: 'constant',
      result_type: 'number',
      value: 30,
      value_type: 'number'
    },
    {
      type: 'constant',
      result_type: 'text',
      value: 'days',
      value_type: 'string'
    }
  ]
};

// Helper function to check formula type
function isFunction(formula: Formula): formula is FunctionFormula {
  return formula.type === 'function';
}

function isProperty(formula: Formula): formula is PropertyFormula {
  return formula.type === 'property';
}

// Process formula recursively
function processFormula(formula: Formula): string {
  switch (formula.type) {
    case 'constant':
      return `CONST(${formula.value})`;
    case 'property':
      return `PROP(${formula.name})`;
    case 'function':
      const args = formula.args.map(processFormula).join(', ');
      return `${formula.name.toUpperCase()}(${args})`;
    case 'operator':
      const operands = formula.args.map(processFormula).join(` ${formula.operator} `);
      return `(${operands})`;
    case 'symbol':
      return `SYMBOL(${formula.name})`;
    default:
      return 'UNKNOWN';
  }
}

// Example usage
console.log(processFormula(greetingFormula));
// Output: CONCAT(CONST(Hello, ), PROP(Name), CONST(!))

console.log(processFormula(statusFormula));
// Output: IF(LARGER(PROP(Age), CONST(18)), CONST(Adult), CONST(Minor))

Install with Tessl CLI