@almadar/operators 0.1.0

package/LICENSE

@@ -0,0 +1,72 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Almadar FZE
+Licensed Work:        KFlow Builder / Almadar
+                      The Licensed Work is (c) 2025-2026 Almadar FZE.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      non-commercial purposes and for internal evaluation.
+                      Production use for commercial purposes requires a
+                      commercial license from the Licensor.
+Change Date:          2030-02-01
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+---
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+ADDITIONAL TERMS:
+
+Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
+
+TRADEMARKS:
+
+"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
+Almadar FZE. You may not use these trademarks without prior written
+permission from Almadar FZE.
+
+For licensing inquiries: licensing@almadar.io

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Almadar Operators - Single Source of Truth
+ *
+ * This package defines all S-expression operators used across:
+ * - almadar-core (TypeScript types)
+ * - almadar-evaluator (TypeScript runtime)
+ * - almadar-std (TypeScript metadata)
+ * - orbital-rust (Rust evaluator)
+ *
+ * @packageDocumentation
+ */
+export type OperatorCategory = 'arithmetic' | 'comparison' | 'logic' | 'control' | 'effect' | 'collection' | 'std-math' | 'std-str' | 'std-array' | 'std-object' | 'std-time' | 'std-validate' | 'std-format' | 'std-async' | 'std-nn' | 'std-tensor' | 'std-train';
+export type TargetPlatform = 'ts' | 'rust' | 'python';
+export interface CategoryMeta {
+    description: string;
+    target: TargetPlatform[];
+}
+export interface OperatorMeta {
+    category: OperatorCategory;
+    minArity: number;
+    maxArity: number | null;
+    returnType: string;
+    description: string;
+    hasSideEffects?: boolean;
+}
+export interface OperatorsSchema {
+    version: string;
+    description: string;
+    categories: Record<string, CategoryMeta>;
+    operators: Record<string, OperatorMeta>;
+}
+/** The canonical operators schema */
+export declare const OPERATORS_SCHEMA: OperatorsSchema;
+/** All operator definitions */
+export declare const OPERATORS: Record<string, OperatorMeta>;
+/** All category definitions */
+export declare const CATEGORIES: Record<string, CategoryMeta>;
+/** All operator names */
+export declare const OPERATOR_NAMES: string[];
+/** Get operator metadata */
+export declare function getOperatorMeta(name: string): OperatorMeta | undefined;
+/** Check if operator exists */
+export declare function isKnownOperator(name: string): boolean;
+/** Check if operator has side effects */
+export declare function isEffectOperator(name: string): boolean;
+/** Check if operator can be used in guards (no side effects) */
+export declare function isGuardOperator(name: string): boolean;
+/** Get all operators in a category */
+export declare function getOperatorsByCategory(category: OperatorCategory): string[];
+/** Get operators for a target platform */
+export declare function getOperatorsForTarget(target: TargetPlatform): string[];
+/** Validate operator arity */
+export declare function validateOperatorArity(name: string, argCount: number): string | null;
+export interface OperatorStats {
+    total: number;
+    byCategory: Record<string, number>;
+    byTarget: Record<TargetPlatform, number>;
+    withSideEffects: number;
+}
+export declare function getOperatorStats(): OperatorStats;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH,MAAM,MAAM,gBAAgB,GACtB,YAAY,GACZ,YAAY,GACZ,OAAO,GACP,SAAS,GACT,QAAQ,GACR,YAAY,GACZ,UAAU,GACV,SAAS,GACT,WAAW,GACX,YAAY,GACZ,UAAU,GACV,cAAc,GACd,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,WAAW,CAAC;AAElB,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEtD,MAAM,WAAW,YAAY;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC3C;AAMD,qCAAqC;AACrC,eAAO,MAAM,gBAAgB,EAAgB,eAAe,CAAC;AAE7D,+BAA+B;AAC/B,eAAO,MAAM,SAAS,8BAA6B,CAAC;AAEpD,+BAA+B;AAC/B,eAAO,MAAM,UAAU,8BAA8B,CAAC;AAEtD,yBAAyB;AACzB,eAAO,MAAM,cAAc,UAAyB,CAAC;AAErD,4BAA4B;AAC5B,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE;AAED,+BAA+B;AAC/B,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,yCAAyC;AACzC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGtD;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED,sCAAsC;AACtC,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAI3E;AAED,0CAA0C;AAC1C,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,CAOtE;AAED,8BAA8B;AAC9B,wBAAgB,qBAAqB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAaf;AAMD,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CA2BhD"}

package/dist/index.js

@@ -0,0 +1,99 @@
+/**
+ * Almadar Operators - Single Source of Truth
+ *
+ * This package defines all S-expression operators used across:
+ * - almadar-core (TypeScript types)
+ * - almadar-evaluator (TypeScript runtime)
+ * - almadar-std (TypeScript metadata)
+ * - orbital-rust (Rust evaluator)
+ *
+ * @packageDocumentation
+ */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const operatorsPath = join(__dirname, '..', 'operators.json');
+const operators = JSON.parse(readFileSync(operatorsPath, 'utf-8'));
+// ============================================================================
+// Exports
+// ============================================================================
+/** The canonical operators schema */
+export const OPERATORS_SCHEMA = operators;
+/** All operator definitions */
+export const OPERATORS = OPERATORS_SCHEMA.operators;
+/** All category definitions */
+export const CATEGORIES = OPERATORS_SCHEMA.categories;
+/** All operator names */
+export const OPERATOR_NAMES = Object.keys(OPERATORS);
+/** Get operator metadata */
+export function getOperatorMeta(name) {
+    return OPERATORS[name];
+}
+/** Check if operator exists */
+export function isKnownOperator(name) {
+    return name in OPERATORS;
+}
+/** Check if operator has side effects */
+export function isEffectOperator(name) {
+    const meta = OPERATORS[name];
+    return meta?.hasSideEffects === true;
+}
+/** Check if operator can be used in guards (no side effects) */
+export function isGuardOperator(name) {
+    const meta = OPERATORS[name];
+    return meta !== undefined && !meta.hasSideEffects;
+}
+/** Get all operators in a category */
+export function getOperatorsByCategory(category) {
+    return Object.entries(OPERATORS)
+        .filter(([_, meta]) => meta.category === category)
+        .map(([name]) => name);
+}
+/** Get operators for a target platform */
+export function getOperatorsForTarget(target) {
+    return Object.entries(OPERATORS)
+        .filter(([_, meta]) => {
+        const cat = CATEGORIES[meta.category];
+        return cat?.target.includes(target);
+    })
+        .map(([name]) => name);
+}
+/** Validate operator arity */
+export function validateOperatorArity(name, argCount) {
+    const meta = OPERATORS[name];
+    if (!meta)
+        return `Unknown operator: ${name}`;
+    if (argCount < meta.minArity) {
+        return `Operator '${name}' requires at least ${meta.minArity} argument(s), got ${argCount}`;
+    }
+    if (meta.maxArity !== null && argCount > meta.maxArity) {
+        return `Operator '${name}' accepts at most ${meta.maxArity} argument(s), got ${argCount}`;
+    }
+    return null;
+}
+export function getOperatorStats() {
+    const byCategory = {};
+    const byTarget = { ts: 0, rust: 0, python: 0 };
+    let withSideEffects = 0;
+    for (const [name, meta] of Object.entries(OPERATORS)) {
+        // By category
+        byCategory[meta.category] = (byCategory[meta.category] || 0) + 1;
+        // By target
+        const cat = CATEGORIES[meta.category];
+        if (cat) {
+            for (const target of cat.target) {
+                byTarget[target]++;
+            }
+        }
+        // Side effects
+        if (meta.hasSideEffects)
+            withSideEffects++;
+    }
+    return {
+        total: OPERATOR_NAMES.length,
+        byCategory,
+        byTarget,
+        withSideEffects,
+    };
+}