ideav-local-associative-js

JavaScript port of IdeaV Local using Bun, Express, and Links Notation with Link Foundation tools.

Features

• Bun + Express server with Links Notation endpoints
• Full CRUD API for link database operations via @link-foundation/links-client
• ILinks API compatible with Platform.Data interface
• RecursiveLinks API for nested data structures and Links Notation conversions
• Objects API for hierarchical object storage (compatible with ideav/local data model)
• Filtering capabilities with text, numeric, range, and reference operations
• Export/Import support for Links Notation, JSON, and CSV formats
• CLI arguments via lino-arguments for --port, --host, --db-path
• lino-arguments configuration from CLI args, env vars, and .lenv file
• Cross-runtime testing with test-anywhere

Prerequisites

Install link-cli globally (requires .NET):

dotnet tool install --global clink

Installation

bun install
# or
npm install

Running the Server

# Development mode with hot reload
bun run dev

# Production mode
bun run start

# With CLI arguments
bun run start -- --port 8080 --host 127.0.0.1
# or
bun run start -- -p 8080 -h 127.0.0.1

# With custom database path
bun run start -- --db-path /path/to/db.links

API Endpoints

Health Check

curl http://localhost:3000/health
# Response: (status: ok)

Parse Links Notation

curl -X POST http://localhost:3000/parse \
  -H 'Content-Type: text/plain' \
  --data '(status: ok)'

Links CRUD API

All responses use Links Notation format: (id: source target)

Create a link:

# Using Links Notation
curl -X POST http://localhost:3000/links \
  -H 'Content-Type: text/plain' \
  --data '(100 200)'

# Using JSON
curl -X POST http://localhost:3000/links \
  -H 'Content-Type: application/json' \
  --data '{"source": 100, "target": 200}'
# Response: (1: 100 200)

Read all links:

curl http://localhost:3000/links
# Response:
# (1: 100 200)
# (2: 300 400)

Read a specific link:

curl http://localhost:3000/links/1
# Response: (1: 100 200)

Update a link:

curl -X PUT http://localhost:3000/links/1 \
  -H 'Content-Type: application/json' \
  --data '{"source": 100, "target": 500}'
# Response: (1: 100 500)

Delete a link:

curl -X DELETE http://localhost:3000/links/1
# Response: (deleted: ok)

ILinks API (Platform.Data Compatible)

Advanced API compatible with the Platform.Data ILinks interface.

Count links:

curl -X POST http://localhost:3000/ilinks/count \
  -H 'Content-Type: application/json' \
  --data '{"restriction": null}'
# Response: (count: 5)

Iterate through links:

curl -X POST http://localhost:3000/ilinks/each \
  -H 'Content-Type: application/json' \
  --data '{"restriction": [100, 0]}'
# Response: All links with source=100

Create via ILinks:

curl -X POST http://localhost:3000/ilinks/create \
  -H 'Content-Type: application/json' \
  --data '{"substitution": [100, 200]}'
# Response: (1: 100 200)

Update via ILinks:

curl -X POST http://localhost:3000/ilinks/update \
  -H 'Content-Type: application/json' \
  --data '{"restriction": [1], "substitution": [100, 500]}'
# Response: (1: 100 500)

Delete via ILinks:

curl -X POST http://localhost:3000/ilinks/delete \
  -H 'Content-Type: application/json' \
  --data '{"restriction": [1]}'
# Response: (deleted: 1)

RecursiveLinks API (Nested Data Structures)

Work with nested arrays and objects, converting to/from Links Notation.

Create from nested array:

curl -X POST http://localhost:3000/recursive/from-array \
  -H 'Content-Type: application/json' \
  --data '{"data": [[1, 2], [3, 4]]}'
# Response: (created: [linkId1, linkId2])

Convert to Links Notation:

curl -X POST http://localhost:3000/recursive/to-notation \
  -H 'Content-Type: application/json' \
  --data '{"data": [[1, 2], [3, 4]]}'
# Response: ((1 2) (3 4))

Parse Links Notation:

curl -X POST http://localhost:3000/recursive/from-notation \
  -H 'Content-Type: application/json' \
  --data '{"notation": "((1 2) (3 4))"}'
# Response: (data: [[1, 2], [3, 4]])

Objects API (Hierarchical Storage)

Store and manage hierarchical objects with type, parent, order, and value attributes.

Create an object:

curl -X POST http://localhost:3000/objects \
  -H 'Content-Type: application/json' \
  --data '{"t": 1, "up": 0, "ord": 1, "val": 100}'
# Response: (1: (t: 1) (up: 0) (ord: 1) (val: 100))

List objects:

curl http://localhost:3000/objects
# With filters:
curl "http://localhost:3000/objects?type=1&parent=0"

Get object children:

curl http://localhost:3000/objects/1/children

Filtered Links API

Query links with powerful filtering capabilities.

Filter links:

curl -X POST http://localhost:3000/links/filter \
  -H 'Content-Type: application/json' \
  --data '{"filters": {"source": "100", "target": ">150"}, "limit": 10}'

Filter operators:

• Equality: "100" (exact match)
• Negation: "!100" (not equal)
• Range: "10..20" (between 10 and 20)
• Greater/Less: ">100", "<50", ">=100", "<=50"
• List: "1,2,3" (in list)
• Contains: "*text*" (contains)
• Starts with: "text*"
• Ends with: "*text"
• Reference: "@123" (reference to object 123)

Export/Import API

Export and import links in multiple formats.

Export links:

# Links Notation (default)
curl http://localhost:3000/export

# JSON format
curl "http://localhost:3000/export?format=json"

# CSV format
curl "http://localhost:3000/export?format=csv"

Import links:

# Auto-detect format
curl -X POST http://localhost:3000/import \
  -H 'Content-Type: text/plain' \
  --data '(1: 100 200)
(2: 300 400)'

# JSON format
curl -X POST "http://localhost:3000/import?format=json" \
  -H 'Content-Type: application/json' \
  --data '[{"source": 100, "target": 200}]'

API Information

Get list of all available endpoints:

curl http://localhost:3000/api

Configuration

Configuration supports three sources with the following priority (highest first):

1. CLI arguments: --port, --host, --db-path
2. Environment variables: PORT, HOST, DB_PATH
3. .lenv file using Links Notation:

server.port: 3000
server.host: 0.0.0.0
db.path: data/linkdb.links

CLI Options

Option	Alias	Description	Default
--port	-p	Port to listen on	3000
--host	-h	Host to bind to	0.0.0.0
--db-path	-d	Path to the links database	data/linkdb.links
--help		Show help

Development

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

# Run all checks
npm run check

Dependencies

Package	Purpose
@link-foundation/links-client	Link-cli database client
links-notation	Links Notation parser/formatter
lino-arguments	CLI args, env vars, and .lenv config
express	HTTP server
test-anywhere	Cross-runtime testing (dev dependency)

Links

• Issue #1 - Original requirements
• ideav/local - Original PHP/Python implementation
• link-cli - Links Theory database CLI
• links-client - JavaScript client for link-cli
• links-notation - Data notation format

License

Unlicense