# nc-server/lib Files Reference

This document provides a reference of all files in `/Volumes/nc/nc-server/lib`, their purpose and features.

## Root-Level Library Files

### ansicolors.lua

**Purpose**: ANSI color code utilities for terminal output.

**Features**:

- Color formatting for terminal output
- Support for bright, dim, underscore, blink, reverse, and hidden text attributes
- Predefined color functions for common colors (red, green, blue, yellow, cyan, magenta, white)
- Background color support

### array-util.lua

**Purpose**: Array manipulation utilities.

**Public Functions**:

- `orderedIndexArray(t)` - Get sorted array of table keys
  - Sorts by type first (boolean < number < string < others)
  - Numbers and strings sorted by value
  - Returns array of keys in sorted order
- `orderedPairs(t)` - Iterate over table in sorted key order
  - Returns iterator function (like pairs() but sorted)
  - Uses `__orderedIndex` internally to cache sorted keys

### auth.lua

**Purpose**: Authentication and authorization module.

**Features**:

- `currentAuthTable()` - Get current auth table (thread-aware)
- `setCurrentAuthTable(auth)` - Set current auth table
- `currentUserId()` - Get current user login_id
- `currentOrganizationId()` - Get current organization ID
- `setCurrentOrganization(orgId)` - Set current organization
- `saveAuthRecord(session)` - Save auth session to database
- `loadAuth(loginId, password)` - Load auth from database
- `hashPassword(password)` - Hash password
- `logout(paramTbl, checkParameter)` - Logout user
- Thread-local auth storage for coroutine support
- Organization context switching
- Session management
- Token validation
- Permission checking

### base36.lua

**Purpose**: Base36 encoding/decoding utilities.

**Public Functions**:

- `encode(num)` - Encode number to base36 string
  - Supports positive numbers only
  - Uses alphabet: 0-9, A-Z
  - Returns string representation
- `encodeDigits(num, digits)` - Encode number with fixed digit count
  - Similar to 4D code_UUIDGet
  - Pads with leading zeros if needed
- `decode(b36)` - Decode base36 string to number
  - Uses tonumber(string, 36)

### base64.lua

**Purpose**: Base64 encoding/decoding (simple version).

**Features**:

- Basic base64 encoding
- Basic base64 decoding

### base64lua.lua

**Purpose**: Base64 encoding/decoding (pure Lua implementation).

**Features**:

- Pure Lua base64 implementation
- No external dependencies

### base64luajit.lua

**Purpose**: Base64 encoding/decoding using LuaJIT FFI.

**Features**:

- FFI-accelerated base64 operations
- High performance encoding/decoding

### console.lua

**Purpose**: Console and terminal utilities.

**Public Functions**:

- `getKeyPressed()` - Get single keypress without Enter (Win: ReadConsoleW, Unix: stty cbreak)
- `waitKeyPressed(allowedKey)` - Wait for allowed key, beeps on wrong key
- `detectTheme()` - Detect terminal theme (dark/light)
  - Checks COLORFGBG, TERM_PROGRAM, environment variables
  - Time-based detection (6AM-6PM = light)
  - macOS Terminal.app settings via defaults
- `getThemeStyle()` - Get theme style for output
- `printThemeInfo()` - Print theme detection information

### coro-thread.lua

**Purpose**: Coroutine-based threading utilities.

**Features**:

- Thread management using coroutines
- Concurrent execution patterns

### coro.lua

**Purpose**: Coroutine utilities and helpers.

**Public Functions**:

- `createSocketCoroutine(fn, socket)` - Create coroutine for socket operations
  - Associates coroutine with specific socket
- `currentThreadSocket()` - Get socket for current coroutine
- `threadSocketArr()` - Get array of all thread sockets
- `threadCount()` - Get number of active threads
- `setMainThread()` - Set main thread context
- `yieldFunction()` - Get/set yield function for coroutines

### curl-ffi.lua

**Purpose**: CURL HTTP client using FFI.

**Features**:

- HTTP/HTTPS requests via libcurl
- FFI bindings for curl
- Request/response handling

### curl.lua

**Purpose**: CURL HTTP client wrapper.

**Features**:

- `get(url, option)` - HTTP GET request
- `post(url, data, option)` - HTTP POST request
- `put(url, data, option)` - HTTP PUT request
- `delete(url, option)` - HTTP DELETE request
- `ftpFileList(ret)` - Parse FTP file listings
- FTP operations with ftp_list_parse library
- Header and data callbacks
- SSL/TLS support
- Custom request options
- Authentication support
- Proxy support
- Cookie handling
- File upload/download
- Response header parsing

### dt.lua

**Purpose**: Date and time utilities.

**Features**:

- `currentDateTime()` - Get current date/time
- `currentString()` - Current date/time as string
- `toString(dateTime)` - Format date/time to string
- `dateTimeParse(str)` - Parse date/time from string
- `isZeroDate(date)` - Check if date is zero/empty
- `secondsAdd(dateTime, seconds)` - Add seconds to date
- `daysAdd(dateTime, days)` - Add days to date
- `monthsAdd(dateTime, months)` - Add months to date
- `yearsAdd(dateTime, years)` - Add years to date
- `diff(date1, date2)` - Difference between dates
- Date/time patterns for PEG parsing
- Julian day number support
- Day of week calculation
- Leap year handling
- Time zone offset support

### execute.lua

**Purpose**: Command execution utilities.

**Public Functions**:

- `getFunction(code)` - Get function from code definition
  - Checks allowed_function.json for permission
  - Loads module and gets function reference
  - Returns function or nil, error
- `runCode(codeArr, data, saveData, parameter)` - Run code array
  - codeArr: Array of code definitions
  - data: Input data
  - saveData: Output data
  - parameter: Optional parameter table
- `runCodeWeb(parameter)` - Run code for web calls
  - parameter.run_code: Code array to run
  - Returns value when parameter.return_value is true
- `runFunction(funcName, data, parameter)` - Run single function
  - funcName: Function name or path
  - Creates code definition and runs it
- `calculate(...)` - Calculate math expression
  - Compiles and executes expression string
- `calculateRec(rec, ...)` - Calculate with record fields
  - Substitutes field values from record
  - Then calls calculate()

### ffi_def_glib.lua, ffi_def_linux.lua, ffi_def_osx.lua, ffi_def_unix.lua, ffi_def_windows.lua

**Purpose**: FFI definitions for different platforms.

**Features**:

- Platform-specific C function definitions
- System library bindings
- Type definitions for FFI

### ffi_def_load.lua

**Purpose**: FFI definition loader.

**Features**:

- Dynamic loading of platform-specific FFI definitions
- Cross-platform FFI support

### filter_map_reduce.lua

**Purpose**: Functional programming utilities (filter, map, reduce).

**Features**:

- `sort()` - Multi-field sorting with ascending/descending order
- `filter()` - Filter array elements
- `map()` - Transform array elements
- `reduce()` - Aggregate array values
- `parseBeforeFromArray()` - Parse string before delimiter
- `arrayFirstKey()` - Get first key from array

### fn.lua

**Purpose**: Lua Fun library - High-performance functional programming for LuaJIT.

**Copyright**: Roman Tsisyk, MIT/X11 License

**Features**:

- **Generators**: `iter()`, `range()`, `duplicate()`, `null()`
- **Slicing**: `take()`, `drop()`, `cycle()`
- **Indexing**: `index()`, `index_map()`, `contains()`
- **Filtering**: `filter()`, `remove()`, `grep()`
- **Reducing**: `reduce()`, `fold()`, `length()`
- **Transformations**: `map()`, `flatten()`, `zip()`, `chain()`
- **Operators module**: Comparison, arithmetic, string, logical, and index operators
- Lazy evaluation support
- High-performance iterator-based operations

### fnutil.lua

**Purpose**: Utility functions extending fn.lua.

**Features**:

- `groupByCalculate()` - Data aggregation with grouping
- `createIndex()` - Create lookup index from array
- `createIndexArray()` - Create array-based index
- `fieldKey()` - Create field-based lookup table
- `uniqueArray()` - Get unique values from generator
- `uniqueConcatArray()` - Unique concatenated values
- `addUniqueToArray()` - Add unique values to array
- `arrayKeyIsUnique()` - Check array key uniqueness
- `recordFilter()` - Filter records with function
- `callArrayParamRecursive()` - Recursive parameter handling
- `uniqueFieldValueGen()` - Generator for unique field values
- `distinctFieldValueArray()` - Distinct field values to array
- `mapFieldValue()` - Map field values
- `mapRecordArrayGen()` - Map and filter records
- `setIdx()` - Set index property on array items

### fs.lua

**Purpose**: Comprehensive file system operations wrapper.

**Features**:

- `filePathFix()` - OS-specific path fixing (Windows/Unix)
- `readFile()` - Read file contents (max 50MB)
- `writeFile()` - Write file contents
- `readJsonFile()` - Read and parse JSON files
- `dirTreeIter()` - Directory tree traversal iterator
- Path change configuration from JSON
- Symbolic link handling
- Windows/Unix path differences
- File attribute operations

### hardware.lua

**Purpose**: Hardware detection and CPU feature detection.

**Public Functions**:

- `cpuSupports(feature)` - Check if CPU supports feature (e.g., "sse4.2")
  - Returns true if feature is present
  - Case-insensitive feature string
- `processIsTranslated()` - Check if running under translation (macOS ARM)
  - Returns "native", "rosetta", or "unknown"
  - Uses sysctlbyname on macOS
- `printInfo()` - Print detailed CPU information
  - CPU brand, codename, clock speed
  - Cache sizes (L1, L2, L3, L4)
  - CPU features list
  - Checks cpuid library if available
- `windowsVersionString()` - Get Windows version as string
  - Returns "2000", "XP", "Vista", "7", "8", "8.1"
- `windowsMinVersion(ver)` - Check if Windows is at least version
  - ver: "2000", "XP", "Vista", "7", "8", "8.1", or number
  - Returns true if current version >= ver

### hash.lua

**Purpose**: Hash value calculation for preferences/JSON data.

**Features**:

- `setHash(prefTxt, fileName, option, hashTbl)` - Calculate and set hash value
- Uses xxhash library for hash128string calculation
- Calculates hash from source text or JSON

### http.lua

**Purpose**: HTTP header parsing utilities.

**Public Functions**:

- `getHeader(header, headerName)` - Extract header value by name
  - header: Full header string
  - headerName: Name of header to extract
  - Returns header value or nil if not found
- `headerValueFound(header, headerName, value)` - Check if header value exists
  - Handles comma-separated and semicolon-separated values
  - Case-insensitive comparison
  - Returns true if value is found in header

### import.lua

**Purpose**: Import utility for selective symbol importing.

**Public Functions**:

- `from(what, keystr)` - Import specific symbols from a module
  - what: Module to import from
  - keystr: Comma-separated list of symbols to import
  - Returns tuple of imported symbols
  - Example: `import.from(math, "exp, log, sqrt")`
- `exec(chunk, chunkname, fenv)` - Execute code chunk
  - Compiles and executes string as code
  - Optional environment table

### json.lua

**Purpose**: JSON encoding/decoding using rapidjson.

**Features**:

- Automatic CPU-specific loading (SSE4.2, SSE2, ARM)
- `fromJson()` - Parse JSON text
- `toJson()` - Encode to JSON (pretty)
- `toJsonRaw()` - Encode to JSON (compact)
- `toJsonKeySorted()` - Encode with sorted keys
- `cleanJson()` - Fix NaN, Infinity, null, cdata, userdata, functions, threads
- `fixNull()` - Convert JSON null to Lua nil
- `fixError()` - Fix encoding errors
- `validJson()` - Validate JSON text
- `printJson()` - Pretty print JSON
- `defaultKeyNameArr()` - Get default key sort order
- Error handling and recovery

### json_sort.lua

**Purpose**: Pure Lua JSON encoder/decoder with key sorting.

**Copyright**: Jeffrey Friedl, Version 20111207.5

**Features**:

- `decode()` - Parse JSON
- `encode()` - Encode to JSON
- `encode_pretty()` - Pretty print JSON with sorted keys
- Strict types support
- Unicode handling
- Error callbacks
- No external dependencies

### lanes.lua

**Purpose**: Multi-threading support for Lua (Lanes library).

**Copyright**: Asko Kauppi, Benoit Germain, MIT/X11 License

**Features**:

- `configure(settings)` - Configure Lanes (nb_keepers, with_timers, allocator, etc.)
- `gen.lua(func,[opt])` - Create a new lane
- Thread pooling with keepers
- Inter-lane communication via linda (channels)
- Separate Lua states per lane
- Timer support
- Protected allocator for LuaJIT
- Thread tracking
- Deep userdata handling
- Lane priority management
- Thread synchronization

### lang.lua

**Purpose**: Language and localization utilities.

**Public Functions**:

- `l(txt, ...)` - Get localized text with formatting (main function)
- `langFormat(txt, ...)` - Format string with JSON table support
- `tag(txt)` - Get tag value from custom language file
- `ll(langTbl, txt, ...)` - Local language lookup with fallback
- `setLangCurrent(language)` - Set current language (en, fi, etc.)
- `printLangTranslations()` - Print all translations for current language
- `getLanguageTbl(param)` - Load language table from JSON files
  - Merges default language with custom language
  - Returns `{hdr = language}` structure
- Language file format: `language/lang_<lang>_message.json`, `language/lang_<lang>_custom.json`

### lfs_ffi.lua

**Purpose**: LuaFileSystem with FFI bindings.

**Features**:

- Fast file system operations using FFI
- Directory traversal
- File attribute queries

### lfs_load.lua

**Purpose**: LuaFileSystem loader wrapper.

**Features**:

- Dynamic loading of LFS library
- Version detection

### ltn12.lua

**Purpose**: Lua TN12 filters and sinks.

**Features**:

- Filter chain construction
- Data transformation filters
- Source/sink patterns

### lz4.lua

**Purpose**: LZ4 compression/decompression.

**Features**:

- LZ4 compress/decompress
- High-speed compression
- FFI bindings for performance

### md5.lua

**Purpose**: MD5 hash calculation.

**Public Functions**:

- `sumhexa(s)` - Calculate MD5 hash as hex string
  - Returns 32-character hex string
  - Supports strings of any length
- `sum(s)` - Calculate MD5 hash as binary
  - Returns raw 16-byte binary hash
  - Use sumhexa() for hex representation

### mffi.lua

**Purpose**: Extended FFI utilities with memory tracking.

**Public Functions**:

- `new(ct, nElem, init)` - Create cdata with configurable tracing/anchoring
  - Behavior controlled by setOption() settings
  - Can trace all allocations or just anchored ones
- `newAnchor(ct, nElem, init)` - Create anchored cdata (prevents GC)
  - Anchors allocation to ffi.allocation table
  - Prevents garbage collection
- `newNoAnchor(ct, nElem, init)` - Create non-anchored cdata
  - Faster, but may be collected if not referenced
- `newAnchorTrace(ct, nElem, init)` - Create anchored cdata with tracing
- `newNoAnchorTrace(ct, nElem, init)` - Create non-anchored cdata with tracing
- `newNoAnchorBasic(ct, nElem, init)` - Alias for original ffi.new (no tracing)
- `free(ptr)` - Free anchored allocation
  - Removes from allocation table
- `setOption(opt)` - Set tracing options
  - opt.trace_all: true/false enables/disables all tracing
- `loadDll(fileName, option)` - Load DLL with automatic path discovery
  - Searches bin/ directory and subdirectories
  - Handles .dll, .so, .dylib suffixes
  - option: "no-error" suppresses errors, "no-init" for Windows no-init
- `loadDllAnchor` - Table of loaded DLLs (prevents unloading)
- `allocationIdTable()` - Get all allocations as sorted array
- `printAllocation()` - Print all allocations (debugging)
- `errorText()` - Get system error text from errno
- `invalidWinHandle(handle)` - Check if Windows handle is invalid
- `isNull(pointer)` - Check if pointer is null
- `isNotNull(pointer)` - Check if pointer is not null
- `cstr(str, warning)` - Convert string to C string (uint8_t array)
  - Warning: Prints warning when called
- `cstrAnchor(str)` - Convert string to anchored C string
- `createBuffer(datalen)` - Create buffer of specified size
- `mallocChar(str)` - Allocate C string with malloc()
- `freeChar(cStr, option)` - Free C string allocated with mallocChar
- `copyStringToBuffer(buf, str, strlen)` - Copy string to buffer
- `tableToCharArray(arg)` - Convert array to char*[]
- `fixCHeader(str)` - Convert C #define to static const int
- `ReadWriteMemoryBarrier` - Platform-specific memory barrier
- `loadMsvcr(loadVersion120)` - Load MSVC runtime library (Windows)
- `loadMsvcp(loadVersion120)` - Load MSVC++ runtime library (Windows)
- `loadWinUcrt()` - Load all Windows UCRT DLLs from ucrt/ directory

### mime.lua

**Purpose**: MIME encoding/decoding (LuaSocket).

**Public Functions**:

- `encode(name, opt1, opt2)` - Get encoder filter by name
  - name: "base64", "quoted-printable", or "default"
  - Returns ltn12 filter for encoding
- `decode(name, opt1, opt2)` - Get decoder filter by name
  - name: "base64", "quoted-printable", or "default"
  - Returns ltn12 filter for decoding
- `wrap(name, opt1, opt2)` - Get line wrap filter
  - name: "text", "base64", "quoted-printable", or "default"
  - opt1: Line length (default 76)
- `normalize(marker)` - End-of-line normalization filter
- `stuff()` - Dot-stuffing filter (for SMTP)
- encodet table: Encoder implementations
- decodet table: Decoder implementations
- wrapt table: Wrapper implementations

### murmurhash.lua

**Purpose**: MurmurHash non-cryptographic hash.

**Public Functions**:

- `hash32(data, len, seed)` - 32-bit hash (x86 version)
  - Uses FFI to call libhash
  - Returns hex string
- `hash128(data, len, seed)` - 128-bit hash (x64 version)
  - Returns formatted hex string "x-x-x-x"
- `hash32lua(data, len, seed)` - Pure Lua 32-bit hash
  - No external library needed
- `hash32_x86(data, len, seed)` - FFI x86 32-bit hash
- `hash128_x86(data, len, seed)` - FFI x86 128-bit hash
- `hash128_x64(data, len, seed)` - FFI x64 128-bit hash

### peg.lua

**Purpose**: Parsing Expression Grammar (PEG) library wrapper around lpeg2.

**Features**:

- `match(string, pattern, ...)` - Match pattern against string
- `toPattern(patt)` - Convert to pattern
- `least(patt, count)` - Match at least count times
- `most(patt, count)` - Match at most count times
- `leastMost(patt, countLeast, countMost)` - Match between counts
- `other(patt, leastCount)` - Match anything except pattern
- `find(str, pattern, init, plain)` - Find pattern in string
- `replace(str, pattern, replacement)` - Replace pattern
- `endsWith(str, pattern)` - Check if string ends with pattern
- `startsWith(str, pattern)` - Check if string starts with pattern
- `split(str, sep)` - Split string by separator
- `iterateLines(str, fn)` - Iterate over lines
- Predefined patterns: digit, space, whiteSpace, quoted, etc.
- UTF-8 normalization support
- Comment parsing (single and multi-line)
- Long string parsing [=[ ]=]

### pllua.lua

**Purpose**: PostgreSQL PL/Lua extension example.

**Features**:

- Example of creating PL/Lua functions
- Database integration example

### podofo.lua

**Purpose**: PDF encryption library wrapper (PoDoFo).

**Features**:

- PDF encryption via libpodofoencrypt
- Cross-platform DLL loading

### printer.lua

**Purpose**: Printer interface for Windows/Unix/Mac.

**Features**:

- `getPrinterList()` - List available printers
- `exists(name)` - Check if printer exists
- `getDefaultPrinter()` - Get default printer
- `setDefaultPrinter(name)` - Set default printer
- `printData(printerName, lpData, docName, copies)` - Print data
- Windows: Uses winspool.drv
- Unix/Mac: Uses CUPS library

### queue.lua

**Purpose**: Queue data structure.

**Features**:

- `push(obj)` - Add to queue
- `pop()` - Remove from queue
- `size()` - Get queue size
- `reset()` - Clear queue

### recdata.lua

**Purpose**: Record data access with dot notation and array indexing.

**Features**:

- `get(rec, tag, showError)` - Get value from record using dot notation
- `set(rec, tag, newValue)` - Set value using dot notation
- Supports array indexing: `meta_data[2]`
- Supports query syntax: `meta_data[?key=='value']`
- `getDot()` - Optimized dot-notation getter
- `setDot()` - Optimized dot-notation setter
- Handles nested structures
- JSON string auto-parsing

### rest.lua

**Purpose**: REST API server implementation.

**Features**:

- HTTP request parsing (GET, POST, PUT, DELETE, OPTIONS)
- JSON request/response handling
- Compression support (brotli, gzip, lz4)
- Basic authentication
- Chunked transfer encoding
- WebSocket support
- Plugin loading system
- Request caching
- Cookie handling
- CORS support
- `answerError()` - Create error response
- `answerOk()` - Create success response
- `loadPlugins()` - Load REST API plugins
- `tcpAnswer()` - Handle TCP request
- `tcpClose()` - Close connection

### result_cache.lua

**Purpose**: Result caching for query results.

**Features**:

- `saveResultCacheRecord(savedRecName, tbl, addTimestamp, saveCount)` - Save to cache
- `loadResultCache(savedRecName, jsonTagName)` - Load from cache
- Timestamp-based cache keys
- Automatic old record cleanup
- Database-backed cache (result_cache table)

### ringbuffer.lua

**Purpose**: Unidirectional cdata ring buffer.

**Copyright**: Cosmin Apreutesei, Public Domain

**Features**:

- Circular buffer with cdata support
- `push()` - Add data to buffer
- `pull()` - Read data from buffer
- `checksize()` - Ensure buffer size
- Power-of-2 size optimization
- Dynamic growing

### search.lua

**Purpose**: Search algorithms (binary and interpolating).

**Features**:

- `binaryArray(t, value, reverse, fcompval, nearest)` - Binary search on array
- `binaryRecord(t, key, value, reverse, nearest)` - Binary search on records
- `interpolating(t, value, fcompval)` - Interpolating search
- Duplicate value handling
- Custom comparison functions

### selection.lua

**Purpose**: Selection save/load for REST API.

**Features**:

- `saveSelection(paramTbl)` - Save selection to session
- `loadSelection(sessionId)` - Load selection from session
- Session-based selection storage
- 30-minute session timeout
- UUID-based session tokens

### serialize.lua

**Purpose**: Data serialization (JSON, MessagePack, CBOR).

**Features**:

- `fromJson()` / `toJson()` - JSON encoding/decoding
- `fromMpack()` / `toMpack()` - MessagePack encoding/decoding
- `fromCbor()` / `toCbor()` - CBOR encoding/decoding
- Multiple library support (cjson, dkjson, JSON, cmsgpack, fleece, marshal)

### shared_memory.lua

**Purpose**: Cross-platform shared memory (mmap).

**Features**:

- `sharedMemoryCreate(filename, size)` - Create shared memory
- `sharedMemoryConnect(filename, size)` - Connect to existing memory
- `sharedMemoryDisconnect(filename)` - Disconnect
- `sharedMemoryDelete(filename)` - Delete shared memory
- `sharedMemorySize(filename)` - Get size
- `mmapOutCreate()` / `mmapInConnect()` - Typed memory buffers
- `mmapStatusInWait()` - Wait for status change
- `mmapOutWrite()` - Write to shared memory
- `mmapInRead()` - Read from shared memory
- Windows: Uses FileMapping
- Unix: Uses shm_open/mmap

### spiderjs.lua

**Purpose**: SpiderMonkey JavaScript engine wrapper.

**Features**:

- `getVersion()` - Get SpiderMonkey version
- `setDebug(debugState)` - Enable debug mode
- `setPath(rootPath, startPath)` - Set paths
- `newRuntime()` - Create JS VM context
- `freeRuntime(ctx)` - Free JS VM context
- `setCode(ctx, code, functionName, parameterCount)` - Set JS code
- `runCode(ctx, param)` - Run JS code
- `setCallFunction(ctx, functionName, parameterCount)` - Set call function
- Supports Windows, Linux, macOS
- Loads mozjs dynamic library

### sql.lua (not found, may be in subdirectory)

### start.lua

**Purpose**: Application startup and initialization.

**Features**:

- JIT optimization settings
- Path configuration for modules
- Bin path detection
- Platform-specific initialization
- Windows UTF-8 console setup
- Error/assert customization
- Print function override
- `setFilePath(prefixPath)` - Configure module paths
- `setFrom4d(inTxtFrom4d)` - 4D plugin integration
- `loadC()` - Load FFI definitions
- `loadLfs()` - Load LuaFileSystem
- FFI definition loading
- Cross-platform path handling

### svg.lua

**Purpose**: SVG generation and manipulation.

**Features**:

- SVG element creation
- SVG file writing

### table-code.lua

**Purpose**: Table code generation utilities.

### table_sort.lua (not found, may be in subdirectory)

### tbl.lua (not found, may be in subdirectory)

### thread.lua

**Purpose**: Thread management utilities.

**Public Functions**:

- `new()` - Create new thread instance
- `initialize()` - Initialize thread library
- `createLuaState()` - Create new Lua state for thread
- `deleteLuaState()` - Delete Lua state
- `create(functionPointer, name)` - Create new thread
  - functionPointer: C function pointer
  - name: Thread name
- `join(thread)` - Wait for thread to complete
- `detach(thread)` - Detach thread
- `exit()` - Exit current thread
- `yield()` - Yield execution to next thread
- `selfIdString()` - Get current thread ID as string
- Platform-specific implementations for Windows (CreateThread) and POSIX (pthread)

### thread_pool.lua (not found, may be in subdirectory)

### timeout.lua (not found, may be in subdirectory)

### time.lua

**Purpose**: Time utilities (wall-clock, monotonic time, sleeping).

**Public Functions**:

- `epoch()` - Get epoch time in seconds (since 1970-01-01)
- `time()` - Get current time in seconds (same as epoch/10^6 for compatibility)
- `clock()` - Get monotonic time (not affected by system clock changes)
- `sleep(s)` - Sleep for s seconds
- `seconds(prev_sec, decimals, showWarning)` - Get elapsed seconds since prev_sec
- `milliSeconds(prev_millisec, decimals)` - Get elapsed milliseconds
- `microSeconds(prev_microsec, decimals)` - Get elapsed microseconds

**Platform Support**:

- Windows: GetSystemTimeAsFileTime, QueryPerformanceCounter, Sleep
- Linux: clock_gettime (CLOCK_REALTIME, CLOCK_MONOTONIC), nanosleep
- macOS: gettimeofday, clock_gettime_nsec_np, mach_absolute_time

### timer.lua

**Purpose**: Timer/scheduler using Later.js library.

**Public Functions**:

- `calculate(timerParam, isRestCall)` - Calculate timer schedules
  - timerParam: JSON string or table with `rule` array and `count` number
  - Returns array of scheduled times with date strings
- `cleanup()` - Cleanup SpiderMonkey context
- Uses Later.js constraint-based scheduling
- Supports rules like "every 1 day at 00:00", "every 5 min on the 0 min"
- Returns `{total_time, result: [{timer, result, result_text, time}]}`

### timing.lua (not found, may be in subdirectory)

### timer.lua

**Purpose**: Timer utilities.

**Features**:

- Timer creation
- Timer callbacks
- Timeout handling

### uuid.lua

**Purpose**: UUID generation (RFC 4122).

**Copyright**: Rackspace (original), Thijs Schreijer (modifications), Apache License 2.0

**Features**:

- `new()` - Generate UUID v4
- `cryptoRandomUuid()` - Crypto-strength random UUID
- Epoch time-based UUIDs
- MAC address integration
- Random seed management

### util.lua

**Purpose**: General utility functions (large file, 87KB).

**Features**:

- Path utilities: `mainPath()`, `pluginPath()`, `backendPath()`, `preferencePath()`
- String operations: `split()`, `trim()`, `replace()`, `startsWith()`, `endsWith()`
- Table operations: `tableIsEmpty()`, `clone()`, `recToRec()`, `tableEqual()`
- File operations: `readFile()`, `writeFile()`, `fileExists()`, `loadDll()`
- System operations: `isWin()`, `isMac()`, `isLinux()`, `from4d()`, `fromEditor()`
- Math utilities: `fmod()`, `round()`, `floor()`, `ceil()`
- Date/time utilities: `seconds()`, `milliseconds()`, `microseconds()`
- Output functions: `print()`, `printError()`, `printWarning()`, `printInfo()`, `printColor()`
- JSON operations: `jsonMerge()`, `jsonPath()`
- Preference loading: `prf()`, `writePrfFile()`
- Array operations: `addToArray()`, `arrayFirstKey()`, `removeFromArray()`
- Type checking: `isNumber()`, `isString()`, `isTable()`, `isFunction()`
- Error handling: `callPath()`, `getCallPath()`
- Coroutine support for thread-local operations

### util-env.lua

**Purpose**: Environment utilities.

**Features**:

- Environment variable handling
- System detection

### utest.lua

**Purpose**: Unit testing framework.

**Features**:

- Test case definition
- Assertions
- Test reporting

### utf.lua

**Purpose**: UTF-8 encoding/decoding utilities.

**Public Functions**:

- `fixUTF8(s, replacement)` - Fix invalid UTF-8 sequences
  - Returns fixed string and table of invalid positions
- `next2(s, i)` - Get next UTF-8 character position
  - Returns next position and valid flag
- `iter(s, previ)` - Iterate over UTF-8 characters
- `codepointToUtf8(codepoint)` - Convert Unicode codepoint to UTF-8 bytes
- `latin9ToUtf8(latin9String)` - Convert ISO-8859-15 (Latin9) to UTF-8
- `utf8ToLatin9(utf8String)` - Convert UTF-8 to Latin9
- `utf8ToCp1252(utf8String)` - Convert UTF-8 to Windows CP1252
- `normalizeNfc(str)` - Normalize UTF-8 to NFC form
- `gsub(str, pattern, repl)` - UTF-8 aware string replacement
- Reverse compatibility with lua-utf8 library

### utf16.lua

**Purpose**: UTF-16 encoding/decoding utilities.

**Public Functions**:

- UTF-16 to UTF-8 conversion
- UTF-8 to UTF-16 conversion
- surrogate pair handling

### web.lua

**Purpose**: Web utilities (email, FTP).

**Public Functions**:

- `sendEmail(parameter)` - Send email
  - parameter: Table with from, to, cc, bcc, subject, body
  - Uses curl library for SMTP
  - Supports authentication
- `escape(str)` - URL encode string (from curl)
- `getUrl(url)` - HTTP GET request (from curl)
- `ftpFileList(ftpUrl)` - Get FTP file listing (from curl)
- `deleteFtpFile(ftpUrl)` - Delete FTP file (from curl)
- `moveFtpFile(sourceFtpUrl, targetFtpUrl)` - Move/rename FTP file (from curl)
- `sendFtpFile(localFile, ftpUrl)` - Upload file via FTP (from curl)
- `receiveFtpFile(ftpUrl, localFile)` - Download file via FTP (from curl)
- `receiveFtpList(ftpUrl)` - Download FTP directory listing (from curl)

### web-auth.lua

**Purpose**: WebAuthn (FIDO2) passkey authentication.

**Public Functions**:

- `beginRegistration(userId, userName, displayName, rpId, rpName)` - Start passkey registration
  - Returns challenge and credential creation options
  - rpId: Relying party ID (default "localhost")
  - rpName: Relying party name (default "nc")
- `completeRegistration(attestationObject, clientDataJSON, expectedChallenge, expectedOrigin)` - Complete registration
  - Verifies attestation
  - Extracts credential ID and public key
- `beginAuthentication(userId)` - Start passkey authentication
  - Returns challenge and credential request options
- `completeAuthentication(assertion, clientDataJSON, expectedChallenge, expectedOrigin)` - Complete authentication
  - Verifies assertion signature
- `storeCredential(userId, credentialId, public_key, deviceName)` - Store passkey in user record
- `getUserCredential(userId)` - Get all passkeys for user
- `deleteCredential(userId, credentialId)` - Delete passkey

### wepoll.lua

**Purpose**: Event polling (epoll/kqueue wrapper).

**Features**:

- Cross-platform polling
- Event notification

### xxhash.lua

**Purpose**: xxHash fast non-cryptographic hash algorithm.

**Public Functions**:

- `version()` - Get xxhash library version number
- `hash32(input)` - 32-bit hash as hex string
- `hash32num(input)` - 32-bit hash as number
- `hash32string(input)` - 32-bit hash as string
- `hash64(input)` - 64-bit hash as string (alias for hash64string)
- `hash64string(input)` - 64-bit hash as string
- `hash64num(input)` - 64-bit hash as number
- `hash128(input)` - 128-bit hash as hex string
- `hash128string(input)` - 128-bit hash as string
- `new(bits)` - Create streaming hash state
  - bits: 32, 64, or 128
  - Returns state object with update() and digest() methods

## Subdirectories

### barcode/

Barcode generation and scanning.

- **quirc.lua** - QR code recognition library
- **zbar_h.lua** - ZBar FFI definitions
- **zbar.lua** - ZBar barcode scanner wrapper
  **Public Functions**:
  - `scanImage(picturePath)` - Scan image for barcodes
    - Returns array of detected barcodes
    - Supports EAN, Code128, Code39, QR Code, DataBar
    - Image preprocessing with vips
- **zint.lua** - ZInt barcode generator wrapper
  **Public Functions**:
  - `generateBarcode(symbol, input, output, option)` - Generate barcode
    - Supports 100+ barcode types
    - symbol: Barcode type (Code39, Code128, EAN, QR, Data Matrix, Aztec, PDF417, etc.)
    - input: Data to encode
    - output: Output file path
- **zxing.lua** - ZXing barcode library wrapper

### brotli/

Brotli compression.

- **decoder-ffi.lua** - Brotli decoder FFI definitions
- **decoder.lua** - Brotli decoder wrapper
  **Public Functions**:
  - `decode(str)` - Decompress Brotli data
    - Streaming decompression support
- **encoder.lua** - Brotli encoder wrapper
  **Public Functions**:
  - `compress(str, option)` - Compress with Brotli
    - option.quality: Compression level (0-11, default 11)
    - option.lgwin: Log window size (10-24, default 22)
    - option.mode: GENERIC, TEXT, or FONT
    - Streaming compression support

### compress/

Compression libraries.

- **ffi-zlib-old.lua** - Old FFI zlib implementation
- **gzip-old.lua** - Old gzip implementation
- **lz4.lua** - LZ4 compression wrapper (ljlz4)
  **Public Functions**:
  - `version()` - Get LZ4 library version number
  - `compress(src, level)` - Compress with LZ4
    - src: Input string
    - level: Compression level (1-9, default 1)
    - level >= 3 uses LZ4_compressHC (high compression)
    - Returns compressed string with header
  - `decompress(src)` - Decompress LZ4 data
    - Returns original string or nil, error
- **minizip2_h.lua** - Minizip2 FFI definitions
- **minizip2_rw_h.lua** - Minizip2 read/write definitions
- **minizip2_strm_h.lua** - Minizip2 stream definitions
- **minizip2.lua** - Minizip2 ZIP archive wrapper
  **Features**: ZIP file creation and extraction, password protection, file operations within ZIP
- **zlib_h.lua** - Zlib FFI definitions
- **zlib.lua** - Zlib compression wrapper (luapower)
  **Public Functions**:
  - `compress(str, option)` - Compress with zlib/deflate
    - option.format: "deflate", "zlib", or "gzip"
    - option.level: Compression level (0-9, default 6)
    - option.window: Window size (8-15, default 15)
    - option.memory: Memory level (1-9, default 8)
    - 128KB buffer size
    - Streaming compression support
  - `uncompress(str, option)` - Decompress
    - Auto-detects format (deflate/zlib/gzip)
    - Streaming decompression support
- **zstd.lua** - Zstandard compression
  **Features**: Fast compression/decompression, FFI bindings to libzstd

### convert/

Data conversion utilities.

- **base85.lua** - Base85 encoding/decoding
- **cad.lua** - CAD file conversion
- **col.lua** - Color conversion utilities
- **convert.lua** - General data conversion
- **emf2svg.lua** - EMF (Enhanced Metafile) to SVG conversion
- **image-convert.lua** - Image format conversion
- **json_to_json.lua** - JSON to JSON transformation
- **json_to_text.lua** - JSON to plain text conversion
- **json-ffi-parser.lua** - Fast FFI-based JSON parser
- **json-to-xml.lua** - JSON to XML conversion
  - `convert(convertDefinition, inJson, option, extraDataRec, tagStartCallback)` - Convert
  - Supports charset conversion (CP1252, Latin9, UTF-8)
  - Line break handling
  - Empty tag creation option
  - Debug mode
- **markdown.lua** - Markdown processing
- **rsync.lua** - Rsync algorithm implementation
- **text-to-json.lua** - Text to JSON conversion
- **xml-to-json-definition-convert.lua** - XML to JSON schema conversion
- **xml-to-json.lua** - XML to JSON conversion

### db/

Database access layer (50 files).

- **call-rest.lua** - REST API calls from database queries
- **change-data.lua** - Data change tracking system
- **database-mdb-tools.lua** - MDB Tools driver
- **database-mysql.lua** - MySQL database driver
- **database-odbc-ffi_h.lua** - ODBC FFI definitions
- **database-odbc-ffi.lua** - ODBC FFI driver
- **database-odbc.lua** - ODBC driver wrapper
- **database-postgre-libpq.lua** - PostgreSQL with libpq
- **database-postgre-pgmoon.lua** - PostgreSQL with pgmoon
- **database-postgre.lua** - PostgreSQL driver wrapper
- **database-rest4d.lua** - REST4D driver
- **database-sqlite.lua** - SQLite database driver
- **dconn.lua** - Database connection manager
  - Connection pooling
  - Organization-specific connections
  - Connection state management
- **dconv.lua** - Data type conversion
- **dload.lua** - Data loading utilities
- **doperation.lua** - Database operations
- **dprf.lua** - Preference loading from database
- **dqjson.lua** - JSON query support
- **dqry.lua** - Query builder
- **dsave.lua** / **dsave2.lua** - Data saving with change tracking
- **dschema-4d.lua** - 4D schema definitions
- **dschema.lua** - Database schema manager
  - Table definitions
  - Field definitions
  - Primary keys
  - Foreign keys
- **dschemafld.lua** - Schema field operations
- **dschemasql.lua** - SQL generation from schema
- **dseq.lua** / **dseq4d.lua** - Sequence management
- **dsql-old.lua** - Old SQL generation
- **dsql.lua** - SQL query builder
- **lock.lua** - Database locking mechanism
- **mysql_h.lua** - MySQL FFI definitions
- **mysql.lua** - MySQL client wrapper
- **pgproc-ffi.lua** - PostgreSQL procedures FFI
- **pgproc.lua** - PostgreSQL stored procedures
- **plg4d_api_x64.lua** - 4D plugin API (64-bit)
- **plg4d_api.lua** - 4D plugin API definitions
- **plg4d_public_types_x64.lua** - 4D public types (64-bit)
- **plg4d_public_types.lua** - 4D public types
- **plg4d.lua** - 4D plugin integration
- **qry.lua** - Query execution utilities
- **sqlite3-ffi.lua** - SQLite FFI definitions
- **sqlite3-old.lua** - Old SQLite client
- **sqlite3.lua** - SQLite client wrapper
- **uuid-4d.lua** - 4D UUID functions

### draw/

Drawing and graphics.

### excel/

Excel file handling.

### fsevent/

File system events.

### graphics/

Graphics libraries.

### lpeglj/

OpenGL/EGL bindings.

### luacs/

Lua cryptography.

### luasodium/

Libsodium cryptography wrapper.

### message/

Messaging utilities.

### net/

Networking utilities (20 files).

- **cookie.lua** - HTTP cookie handling
- **fd-client.lua** - File descriptor client
- **fd-send-win.lua** - File descriptor send (Windows)
- **fd-send.lua** - File descriptor send (Unix)
- **fd-server.lua** - File descriptor server
- **http3-lsquic-client.lua** - HTTP/3 client using LSQUIC
- **http3-lsquic-program.lua** - LSQUIC HTTP/3 program
- **http3-lsquic-test_common.lua** - LSQUIC test utilities
- **http3-quiche-client.lua** - HTTP/3 client using Quiche
- **http3-quiche-server.lua** - HTTP/3 server using Quiche
- **lsquic_h.lua** - LSQUIC FFI definitions
- **lsquic-echo-client.lua** - LSQUIC echo client
- **lsquic.lua** - LSQUIC HTTP/3 wrapper
- **nanomsg.lua** - Nanomsg messaging library
- **quiche.lua** - Quiche HTTP/3 wrapper
- **websocket_client.lua** - WebSocket client
- **websocket-permessage-deflate.lua** - WebSocket compression
- **websocket.lua** - WebSocket server/client

### scanner/

Scanner interface.

### system/

System utilities (8 files).

- **crypto.lua** - Cryptographic functions
  - AES encryption/decryption
  - Key derivation
  - Random bytes generation
- **diff.lua** - Diff algorithm implementation
  - Compare text differences
  - Generate diff patches
- **net.lua** - Network utilities
  - MAC address retrieval
  - Network interface information
- **poll.lua** - Event polling (epoll/kqueue)
  - Cross-platform polling
  - Event notification
- **scrypt.lua** - Scrypt key derivation
  - Password hashing
  - Key stretching
- **server.lua** - Server utilities
  - Server initialization
  - Process management
- **sha256.lua** - SHA-256 hashing
  - Hash calculation
  - HMAC support
- **socket.lua** - Socket utilities
  - TCP/UDP sockets
  - Socket options
  - Address manipulation

### table/

Table utilities.

### ui/

UI utilities.

### unicode/

Unicode handling.

### vips/

Image processing (libvips).

### xml/

XML processing (15 files).

- **docx.lua** - DOCX file handling
  - Read/write DOCX files
  - Extract content from DOCX
  - Modify DOCX structure
- **expat_h.lua** - Expat FFI definitions
- **expat.lua** - Expat XML parser wrapper
  - Fast XML parsing
  - Streaming parser
  - Namespace support
- **glue.lua** - XML utility functions
- **slaxml.lua** - Lightweight XML parser
  - Pure Lua implementation
  - No external dependencies
  - Simple API
- **xml-lint.lua** - XML validation and linting
- **xml-schema.lua** - XML Schema support
- **xml-util.lua** - XML utility functions
- **xml-write.lua** - XML generation
- **xml-xslt.lua** - XSLT transformation
- **xml.lua** - Core XML functions
  - `escapeXml()` - Escape XML special characters
  - `parseXml()` - Parse XML string
- **xmllpegparser.lua** - PEG-based XML parser
- **xmlsec-ffi.lua** - XML security FFI
- **xmlsec-xslt-ffi1.lua** - XML security XSLT FFI
- **xmlsec.lua** - XML security (XML Signature, XML Encryption)

### xmlua/

Lua XML bindings.

## Test Folder

`/Volumes/nc/nc-server/test/` - Test directory with subdirectories for different test categories.

**Subdirectories**:

- **ai/** - AI-related tests
- **compress/** - Compression library tests
- **concurrent/** - Concurrency tests
- **convert/** - Data conversion tests
- **database/** - Database tests
- **excel/** - Excel file tests
- **graphics/** - Graphics tests
- **lib/** - Library tests
- **net/** - Network tests
- **nc-preference/** - Preference tests
- **performance/** - Performance tests
- **print/** - Printing tests
- **report/** - Report generation tests
- **ui/** - UI tests
- **xml/** - XML tests
- **yue/** - Yue library tests

**Files**:

- `highest-loopable-number-test.lua` - Loop performance test

## Tool Folder

`/Volumes/nc/nc-server/tool/` - Utilities and tools for development.

**Subdirectories**:

- **caddy/** - Caddy web server configuration
- **code-change/** - Code change tracking tools
- **convert/** - Data conversion tools
- **convert-code/** - Code conversion utilities
- **fix-code/** - Code fixing tools
- **lib/** - Tool library files
- **pdf/** - PDF processing tools
- **profile/** - Profiling tools
- **report-convert/** - Report conversion tools
- **unicode/** - Unicode utilities

**Files**:

- `create-links.sh` - Script to create symbolic links

## Summary

Total documented:

- **70 root-level lib files** - Core Lua library files
- **300+ files in subdirectories** - Organized by functionality

### Key Libraries

| Category | Files | Description |
|----------|-------|-------------|
| **Barcode** | 5 | QR code, barcode scanning/generation (ZBar, Zint, ZXing, Quirc) |
| **Brotli** | 3 | Brotli compression (encoder, decoder, FFI) |
| **Compress** | 9 | Zlib, Zstd, Minizip, Gzip compression |
| **Convert** | 16 | Data format conversion (JSON, XML, Markdown, Base85, EMF, CAD) |
| **Database** | 50 | Database drivers (MySQL, PostgreSQL, SQLite, 4D, ODBC, REST4D) |
| **Net** | 20 | Networking (HTTP/3, WebSocket, Nanomsg, QUIC, LSQUIC) |
| **System** | 8 | System utilities (crypto, diff, poll, server, socket) |
| **XML** | 15 | XML processing (Expat, XML security, DOCX, XSLT) |
| **Auth** | - | Authentication/authorization module |
| **Date/Time** | - | Date/time utilities (dt.lua, time.lua) |
| **File System** | - | File operations (fs.lua, lfs_ffi.lua) |
| **Functional** | - | Functional programming (fn.lua, fnutil.lua) |
| **JSON** | - | JSON encoding/decoding (json.lua, json_sort.lua) |
| **HTTP** | - | HTTP client (curl.lua, curl-ffi.lua) |
| **Multithreading** | - | Threading support (lanes.lua, coro.lua) |
| **Parsing** | - | PEG parsing (peg.lua) |
| **REST** | - | REST API server (rest.lua) |
| **Shared Memory** | - | Cross-platform shared memory (shared_memory.lua) |
| **Test** | - | Comprehensive test suite |
| **Tool** | - | Development utilities |

### Platform Support

- **Windows** - Full support with Windows-specific FFI definitions
- **macOS** - Full support with Unix FFI definitions
- **Linux** - Full support with Linux-specific FFI definitions
- **4D Plugin** - Integration support via plg4d

### External Dependencies

- **zlib** - Compression
- **brotli** - Brotli compression
- **libzstd** - Zstandard compression
- **libcurl** - HTTP client
- **libzbar** - Barcode scanning
- **libzint** - Barcode generation
- **libvips** - Image processing
- **libexpat** - XML parsing
- **libsodium** - Cryptography
- **mozjs** - JavaScript engine (SpiderMonkey)
