@homedev/framework 1.0.6 → 1.0.7

package/README.md

@@ -0,0 +1,673 @@
+# homedev framework
+
+Set of classes and utilities for extending Node.js with common patterns and helpers.
+
+## Logger
+
+### constructor(options?)
+Creates a logger with optional overrides for level, timestamp, and output function.
+
+Arguments:
+- options: partial logger configuration.
+
+Usage:
+```ts
+const log = new Logger({ level: 'WARN', timeStamp: true })
+```
+
+### write(level, ...args)
+Writes a log message at the given level when allowed by current threshold.
+
+Arguments:
+- level: log level name, for example INFO or ERROR.
+- args: message parts to log.
+
+Usage:
+```ts
+log.write('ERROR', 'Something failed', err)
+```
+
+### info(...args), warn(...args), error(...args), debug(...args), verbose(...args)
+Convenience methods for common log levels.
+
+Arguments:
+- args: message parts to log.
+
+Usage:
+```ts
+log.info('Server started')
+log.warn('Retrying request')
+```
+
+## StringBuilder
+
+### constructor(initial?, options?)
+Builds strings efficiently with optional formatting behavior.
+
+Arguments:
+- initial: initial content as string, list of strings, or another builder.
+- options: indentation and line formatting options.
+
+Usage:
+```ts
+const sb = new StringBuilder('hello', { indentSize: 2 })
+```
+
+### setOptions(options)
+Replaces current formatting options.
+
+Arguments:
+- options: new StringBuilder options.
+
+Usage:
+```ts
+sb.setOptions({ lineSeparator: '\n', trim: true })
+```
+
+### clear(), isEmpty(), toString()
+Core buffer controls.
+
+Arguments:
+- clear: none.
+- isEmpty: none.
+- toString: none.
+
+Usage:
+```ts
+sb.clear()
+sb.isEmpty()
+sb.toString()
+```
+
+### indent(), dedent(), getCurrentIndent()
+Controls current indentation level used by formatted line writes.
+
+Arguments:
+- indent: none.
+- dedent: none.
+- getCurrentIndent: none.
+
+Usage:
+```ts
+sb.indent().writeLine('child').dedent()
+```
+
+### getLines(), formatLine(line?)
+Reads content as lines or formats a single line according to options.
+
+Arguments:
+- line: optional source line.
+
+Usage:
+```ts
+const line = sb.formatLine('hello')
+const lines = sb.getLines()
+```
+
+### write(...args), writeLine(...args), writeMap(items, fn)
+Main writing helpers.
+
+Arguments:
+- write: any values to append.
+- writeLine: values to append as formatted lines.
+- writeMap: items list and callback `(item, index, builder)`.
+
+Usage:
+```ts
+sb.write('A', 'B').writeLine('C')
+sb.writeMap([1, 2], n => `${n}\n`)
+```
+
+## Markdown
+
+### header(text, level?)
+Writes a markdown heading and an empty line after it.
+
+Arguments:
+- text: heading content.
+- level: heading level, normalized to 1..6.
+
+Usage:
+```ts
+md.header('Overview', 2)
+```
+
+### codeBlock(code?, language?), endCodeBlock()
+Writes fenced code blocks. Fences are adjusted if code already contains backticks.
+
+Arguments:
+- code: optional code text.
+- language: optional language id.
+
+Usage:
+```ts
+md.codeBlock('const x = 1', 'ts')
+md.codeBlock().writeLine('manual').endCodeBlock()
+```
+
+### link(text, url, title?)
+Writes an inline markdown link.
+
+Arguments:
+- text: visible link text.
+- url: link target.
+- title: optional title attribute.
+
+Usage:
+```ts
+md.link('Docs', '/docs', 'Open docs')
+```
+
+### table(headers, rows)
+Writes a markdown table with automatic column padding.
+
+Arguments:
+- headers: column headers (must not be empty).
+- rows: table rows as arrays.
+
+Usage:
+```ts
+md.table(['Name', 'Age'], [['Alice', '30'], ['Bob', '25']])
+```
+
+### blockquote(text)
+Writes one blockquote line per input line.
+
+Arguments:
+- text: quote text, can be multiline.
+
+Usage:
+```ts
+md.blockquote('Line 1\nLine 2')
+```
+
+### bold(text), italic(text), code(text)
+Inline text style helpers.
+
+Arguments:
+- text: value to wrap in markdown markers.
+
+Usage:
+```ts
+md.bold('Important').write(' ').italic('note').write(' ').code('x')
+```
+
+### item(text), items(values), orderedList(items, start?)
+List helpers for bullets and numbered lists.
+
+Arguments:
+- item: single bullet text.
+- items: array of values or object map.
+- orderedList: list items and optional start index.
+
+Usage:
+```ts
+md.item('One')
+md.items(['A', 'B'])
+md.orderedList(['First', 'Second'], 3)
+```
+
+### horizontalRule(), image(alt, url)
+Writes separators and images.
+
+Arguments:
+- horizontalRule: none.
+- image: alt text and image URL.
+
+Usage:
+```ts
+md.horizontalRule()
+md.image('logo', '/img/logo.png')
+```
+
+### strikethrough(text), highlight(text), subscript(text), superscript(text)
+Additional inline formatting helpers.
+
+Arguments:
+- text: content to format.
+
+Usage:
+```ts
+md.strikethrough('old').write(' ').highlight('new')
+```
+
+### taskList(items)
+Writes GitHub-style task checklist entries.
+
+Arguments:
+- items: list of `{ text, checked }`.
+
+Usage:
+```ts
+md.taskList([{ text: 'Ship release', checked: false }])
+```
+
+### section(text, level?), endSection(), setSectionLevel(level)
+Nested section heading workflow.
+
+Arguments:
+- section: heading text and optional explicit level.
+- endSection: none.
+- setSectionLevel: explicit current section depth.
+
+Usage:
+```ts
+md.section('Chapter')
+md.section('Details')
+md.endSection()
+```
+
+## Array functions
+
+### mapAsync(callback), forEachAsync(callback)
+Async iteration helpers.
+
+Arguments:
+- callback: async callback `(item, index, array)`.
+
+Usage:
+```ts
+const names = await users.mapAsync(async u => u.name)
+await users.forEachAsync(async u => save(u))
+```
+
+### sortBy(selector, ascending?)
+Returns a sorted copy using selector value comparison.
+
+Arguments:
+- selector: function extracting sort value.
+- ascending: sort direction, default true.
+
+Usage:
+```ts
+const ordered = users.sortBy(u => u.age)
+```
+
+### unique(), uniqueBy(selector), groupBy(selector)
+Deduplication and grouping helpers.
+
+Arguments:
+- unique: none.
+- uniqueBy: key selector.
+- groupBy: key selector.
+
+Usage:
+```ts
+ids.unique()
+users.uniqueBy(u => u.id)
+users.groupBy(u => u.role)
+```
+
+### toObject(keySelector, valueSelector?), toObjectWithKey(key)
+Converts arrays into object maps.
+
+Arguments:
+- keySelector: key function.
+- valueSelector: optional value function.
+- key: property name used as key.
+
+Usage:
+```ts
+users.toObject(u => u.id)
+users.toObjectWithKey('id')
+```
+
+### nonNullMap(callback), nonNullMapAsync(callback)
+Maps and removes nullish callback outputs.
+
+Arguments:
+- callback: mapping callback.
+
+Usage:
+```ts
+const values = items.nonNullMap(i => i.optional)
+```
+
+### findOrFail(predicate, message?, thisArg?)
+Finds first match or throws an error.
+
+Arguments:
+- predicate: match function.
+- message: optional error message.
+- thisArg: optional predicate context.
+
+Usage:
+```ts
+const admin = users.findOrFail(u => u.role === 'admin', 'Admin not found')
+```
+
+### selectFor(predicate, selector, message?, thisArg?)
+Finds an item then returns selected projection.
+
+Arguments:
+- predicate: match function.
+- selector: projection function.
+- message: optional error message.
+- thisArg: optional predicate context.
+
+Usage:
+```ts
+const email = users.selectFor(u => u.id === 1, u => u.email)
+```
+
+### createInstances(Target, ...args)
+Creates class instances from array values.
+
+Arguments:
+- Target: constructor function.
+- args: shared constructor args.
+
+Usage:
+```ts
+const models = rows.createInstances(UserModel, commonConfig)
+```
+
+### mergeAll(options?)
+Merges all array objects into one output object.
+
+Arguments:
+- options: merge conflict behavior options.
+
+Usage:
+```ts
+const config = [{ a: 1 }, { b: 2 }].mergeAll()
+```
+
+### Array.flat(value)
+Static helper that flattens array input or wraps non-array values.
+
+Arguments:
+- value: value or array.
+
+Usage:
+```ts
+const result = Array.flat([1, [2, 3]])
+```
+
+## Object functions
+
+### mapEntries(obj, callback)
+Transforms object entries into a new object.
+
+Arguments:
+- obj: source object.
+- callback: returns `[newKey, newValue]`.
+
+Usage:
+```ts
+const mapped = Object.mapEntries({ a: 1 }, ([k, v]) => [k.toUpperCase(), v * 2])
+```
+
+### toList(obj, keyName)
+Converts object map into array items and adds key field.
+
+Arguments:
+- obj: source object.
+- keyName: property name for map key.
+
+Usage:
+```ts
+const rows = Object.toList({ x: { n: 1 } }, 'id')
+```
+
+### deepClone(obj)
+Performs deep clone using structuredClone or JSON fallback.
+
+Arguments:
+- obj: value to clone.
+
+Usage:
+```ts
+const copy = Object.deepClone(original)
+```
+
+### merge(source, target, options?)
+Deep-merges source values into target object.
+
+Arguments:
+- source: source object.
+- target: target object, modified in place.
+- options: conflict and strategy handlers.
+
+Usage:
+```ts
+Object.merge(sourceConfig, targetConfig)
+```
+
+### navigate(obj, callback)
+Walks object tree and allows replace/delete/update while traversing.
+
+Arguments:
+- obj: root object.
+- callback: visitor callback with path context.
+
+Usage:
+```ts
+Object.navigate(data, ({ value }) => value)
+```
+
+### find(from, predicate)
+Returns nested values matching predicate.
+
+Arguments:
+- from: root object.
+- predicate: match function.
+
+Usage:
+```ts
+const ids = Object.find(data, ({ key }) => key === 'id')
+```
+
+### select(from, path, options?)
+Selects nested values with path expressions and options.
+
+Arguments:
+- from: root object.
+- path: selection path.
+- options: set/default/optional behavior.
+
+Usage:
+```ts
+const city = Object.select(user, 'address.city')
+```
+
+## String functions
+
+### toPascal(), capitalize(), toCamel(), toSnake(), toKebab(), changeCase(to)
+Case conversion helpers.
+
+Arguments:
+- changeCase: `to` target format.
+
+Usage:
+```ts
+'hello world'.toCamel()
+'hello_world'.toPascal()
+'sample'.changeCase('upper')
+```
+
+### splitWithQuotes(separator?), splitNested(separator, open, close)
+Split helpers that respect quoted or nested segments.
+
+Arguments:
+- splitWithQuotes: optional separator, default comma.
+- splitNested: separator plus opening/closing delimiters.
+
+Usage:
+```ts
+'a, "b, c", d'.splitWithQuotes(',')
+'a(b,c),d'.splitNested(',', '(', ')')
+```
+
+### toStringBuilder()
+Converts string into StringBuilder initialized by lines.
+
+Arguments:
+- none.
+
+Usage:
+```ts
+const sb = 'line1\nline2'.toStringBuilder()
+```
+
+### toHtmlLink(path?), toRgb(), toArgb()
+Formatting helpers for links and colors.
+
+Arguments:
+- path: optional URL for anchor.
+- toRgb: none, expects hex color string.
+- toArgb: none, expects ARGB hex color string.
+
+Usage:
+```ts
+'Docs'.toHtmlLink('/docs')
+'#ff0080'.toRgb()
+'80ff0080'.toArgb()
+```
+
+### single(char), remove(char), toAlphanum(), toAlpha()
+String cleanup helpers.
+
+Arguments:
+- char: character or regex fragment to collapse/remove.
+
+Usage:
+```ts
+'a---b'.single('-')
+'a-b-c'.remove('-')
+'a!1b'.toAlphanum()
+```
+
+### padBlock(indent, separator?, padder?), tokenize(values, tokenizer?), stripIndent()
+Text block and templating helpers.
+
+Arguments:
+- padBlock: indent size, optional separator and pad char.
+- tokenize: value map and optional token regex.
+- stripIndent: none.
+
+Usage:
+```ts
+'first\nsecond'.padBlock(2)
+'Hello ${name}'.tokenize({ name: 'Ada' })
+```
+
+## File functions
+
+### exists(fileName)
+Checks whether a file is readable.
+
+Arguments:
+- fileName: file path.
+
+Usage:
+```ts
+const ok = await exists('config.json')
+```
+
+### locate(fileName, dirs?)
+Resolves a file path by searching optional directories.
+
+Arguments:
+- fileName: relative or absolute file name.
+- dirs: optional directories to check.
+
+Usage:
+```ts
+const fullPath = await locate('settings.json', ['.', 'config'])
+```
+
+### loadFormat(fileName, options?)
+Reads and parses file content by format or extension matching.
+
+Arguments:
+- fileName: file to load.
+- options: parser map, lookup dirs, or forced format.
+
+Usage:
+```ts
+const data = await loadFormat('data.json')
+```
+
+### writeFormat(filePath, content, options?)
+Encodes and writes content using selected encoder.
+
+Arguments:
+- filePath: destination path.
+- content: value to write.
+- options: encoder map and format.
+
+Usage:
+```ts
+await writeFormat('out.json', { ok: true }, { format: 'json' })
+```
+
+### globMap(pattern, options)
+Runs async mapping over files that match glob pattern(s).
+
+Arguments:
+- pattern: glob pattern or direct file path.
+- options: cwd, optional filter, and async mapper.
+
+Usage:
+```ts
+const files = await globMap('**/*.ts', { cwd: '.', map: async f => f })
+```
+
+### writeOutputs(outputs, options?), writeOutput(output, options?)
+Writes one or many typed outputs with filtering support.
+
+Arguments:
+- outputs/output: output definition(s) with name/value/type/class.
+- options: target dir, class filtering, and pre-write hook.
+
+Usage:
+```ts
+await writeOutputs([{ name: 'a.json', type: 'json', value: { a: 1 } }], { targetDirectory: 'dist' })
+```
+
+### importList(modules, options?), importGlob(patterns, options?)
+Dynamically imports modules from explicit list or glob patterns.
+
+Arguments:
+- modules/patterns: module list or glob list.
+- options: cwd, default-resolution mode, filters, fail strategy, mapper.
+
+Usage:
+```ts
+const mods = await importList(['./tool.ts'])
+const many = await importGlob(['**/*.ts'], { cwd: 'plugins' })
+```
+
+### getCwd(cwd?)
+Resolves effective working directory.
+
+Arguments:
+- cwd: optional absolute or relative directory.
+
+Usage:
+```ts
+const base = getCwd('config')
+```
+
+## Global helpers
+
+### AsyncFunction
+Runtime alias to async function constructor.
+
+Usage:
+```ts
+const fn = new AsyncFunction('x', 'return x * 2')
+```
+
+### defined(value, msg?)
+Returns value when not null/undefined; throws otherwise.
+
+Arguments:
+- value: value to validate.
+- msg: optional error message.
+
+Usage:
+```ts
+const safe = defined(input, 'Input is required')
+```