@nejs/basic-extensions 2.21.0 → 2.22.6

package/.idea/markdown.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MarkdownSettings">
+    <option name="previewPanelProviderInfo">
+      <ProviderInfo name="Mermaid Studio (Chromium browser)" className="MermaidStudio_z.MermaidStudio_R.MermaidStudio_n.MermaidStudio_Q.MermaidStudio_U.MermaidStudio__.JCEFHtmlPanelProvider" />
+    </option>
+  </component>
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/ne-basic-extensions.iml" filepath="$PROJECT_DIR$/.idea/ne-basic-extensions.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/ne-basic-extensions.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/CODE_STYLE.md

@@ -0,0 +1,393 @@
+# Code Style Guide
+
+This document is written for AI assistants generating code in `@nejs` repositories. These are not aspirational conventions — they are patterns extracted from existing code. Follow them precisely so that generated code is indistinguishable from hand-written code.
+
+## Semicolons
+
+Do not use semicolons. Rely on ASI (Automatic Semicolon Insertion). The one exception is class property definitions declared outside of any method or constructor — these get semicolons.
+
+```javascript
+// no semicolons in statements, imports, returns, etc.
+const name = 'Brie'
+const items = [1, 2, 3]
+return this.#settled
+import { Patch } from '@nejs/extension'
+
+// semicolons on class property definitions
+export class Deferred extends Promise {
+  #promise = null;
+  #reject = null;
+  #resolve = null;
+
+  value = null;
+  reason = null;
+
+  #settled = false;
+
+  constructor(options) {
+    // no semicolons inside methods
+    const config = parseOptions(options)
+    let _resolve, _reject
+  }
+}
+```
+
+## Quotes
+
+Use single quotes. Reserve double quotes for strings that contain single quotes. Use template literals when interpolating.
+
+```javascript
+import { Patch } from '@nejs/extension'
+const tag = 'EnumValue'
+const msg = `${this.major}.${this.minor}.${this.patch}`
+```
+
+## Line Length
+
+Aim for 80 columns or fewer. Wrap lines when it makes reading the code more pleasurable — in both code and JSDoc prose. Do not forcibly wrap to the detriment of legibility; a line that reads clearly at 85 columns is better than one awkwardly broken at 79. The goal is readability, not a hard ruler.
+
+## Indentation
+
+2 spaces. No tabs.
+
+## Variable Declarations
+
+`const` by default. `let` only when reassignment is required. Never `var`.
+
+```javascript
+const config = parseOptions(opts)
+let _resolve, _reject
+```
+
+## Arrow Function Parameters
+
+Always parenthesize, even with a single parameter.
+
+```javascript
+values.forEach((value) => this.add(value))
+this.some((element) => element === value)
+```
+
+## Arrow Functions vs `function`
+
+Use arrow functions for callbacks, short lambdas, and closures that don't need their own `this`. Use `function` declarations or named function expressions when the function needs `this` binding, is a Symbol-keyed method, or benefits from a name for stack traces.
+
+```javascript
+// arrow for callbacks
+entries.filter((e) => Array.isArray(e) && e.length === 2)
+
+// named function for Symbol-keyed methods that use `this`
+[Symbol.for('compare')]: data(
+  function compareValue(to) {
+    const {real: lReal, value: lValue} = this
+    // ...
+  }, false, true, false
+)
+```
+
+## Braces on Single-Statement Bodies
+
+If the body of an `if`, `for`, or similar block is a single short statement, omit the braces. Brace everything else.
+
+```javascript
+// unbraced — single short statement
+if (!isLEnum || !isREnum)
+  return false
+
+if (!Array.isArray(array))
+  return false
+
+// braced — multi-line or complex body
+if (config?.resolve && config?.reject) {
+  throw new TypeError(
+    'resolve and reject options cannot be simultaneously provided'
+  )
+}
+```
+
+## `else` and `else if` Placement
+
+Drop `else` and `else if` to a new line. Do not cuddle them on the closing brace line.
+
+```javascript
+if (config?.resolve) {
+  this.#resolve(config?.resolve)
+}
+else if (config?.reject) {
+  this.#reject(config?.reject)
+}
+```
+
+```javascript
+if (Descriptor.isDescriptor(object)) {
+  this._desc = object
+}
+else if (isObject(object) && isValidKey(key)) {
+  this._desc = Object.getOwnPropertyDescriptor(object, key)
+}
+```
+
+## Ternary Formatting
+
+Short ternaries stay on one line. Long ternaries break across lines with `?` and `:` indented, and the closing paren on its own line.
+
+```javascript
+// short
+const store = is.object(store) ? store : undefined
+
+// long
+const config = (options && typeof(options) === 'object'
+  ? options
+  : {}
+)
+```
+
+## Multi-Line Boolean Expressions
+
+Trailing `&&` or `||` at the end of each line. Subsequent conditions align under the first.
+
+```javascript
+return this.major === otherVersion.major &&
+       this.minor === otherVersion.minor &&
+       this.patch === otherVersion.patch &&
+       this.prerelease === otherVersion.prerelease
+```
+
+## Parenthesized Multi-Line Returns
+
+Wrap complex return expressions in parentheses. Opening paren on the `return` line.
+
+```javascript
+return (
+  value instanceof Function &&
+  String(value).includes('=>') &&
+  !String(value).startsWith('bound') &&
+  !Reflect.has(value, 'prototype')
+)
+```
+
+```javascript
+return (array
+  .map((value) => (typeof value))
+  .some((value) => value === 'symbol')
+)
+```
+
+## Destructuring
+
+Destructure at point of use. Renaming during destructuring is common and encouraged when it clarifies intent or prevents collisions.
+
+```javascript
+const { MAJOR, MINOR, PATCH } = SemVer
+const {real: lReal, value: lValue, name: lName, type: lType} = this
+const {real: rReal, value: rValue, name: rName, type: rType} = toObj
+```
+
+## Static Getter Constants
+
+One-liner format when the body is a single return.
+
+```javascript
+static get FULL() { return '*' }
+static get MAJOR() { return 'major' }
+static get MINOR() { return 'minor' }
+```
+
+## Short vs Expanded Getters
+
+Short getters with trivial bodies can be one-liners. Anything beyond a simple return gets expanded.
+
+```javascript
+// one-liner
+get hasObject() { return isObject(this._object) }
+
+// expanded
+get settled() {
+  return this.#settled
+}
+
+get start() {
+  return typeof this.#start === 'function' ? this.#start() : this.#start
+}
+```
+
+## Switch Statements
+
+Compact case/return on the same line when cases are uniform and short. Use `break` or `return` — never fall through silently.
+
+```javascript
+switch (part) {
+  case MAJOR: this[part] = parseInt(semverString); return
+  case MINOR: this[part] = parseInt(semverString); return
+  case PATCH: this[part] = parseInt(semverString); return
+  case PRERELEASE: this[part] = semverString; return
+  case METADATA: this[part] = semverString; return
+  default:
+    break
+}
+```
+
+For switches with longer case bodies, expand normally:
+
+```javascript
+switch (hint) {
+  case 'number':
+    return parseFloat(`${this.major}.${this.minor}`)
+  case 'string':
+    return this.get()
+  default:
+    return null
+}
+```
+
+## `typeof` With Parentheses
+
+`typeof` is sometimes written with parentheses as though it were a function call. Both forms appear, but the parenthesized form is the more natural one in this codebase.
+
+```javascript
+typeof(options) === 'object'
+typeof(config?.executor) === 'function'
+```
+
+## Boolean Coercion and Bitwise Idioms
+
+`!!` for explicit boolean coercion. `!!~` with `indexOf` for existence checks. These are deliberate, not accidental.
+
+```javascript
+return !!this.find((entry) => entry === value)
+return this.some((element) => !!~values.indexOf(element))
+```
+
+## Comparison Operators
+
+Prefer strict equality (`===`). Loose equality (`==`) is acceptable when explicitly intended — it appears in methods like `oneIs` where the caller opts in via a parameter.
+
+```javascript
+// default: strict
+const _skip = this.value === Symbol.for('Enum.NonAssociatedValue')
+
+// intentional loose equality controlled by parameter
+doubleEqualsOkay ? element == value : element === value
+```
+
+## Optional Chaining and Nullish Coalescing
+
+Use freely. These are idiomatic throughout the codebase.
+
+```javascript
+this.inclusive = start?.inclusive ?? true
+configurable: baseDescriptor?.configurable ?? true
+const lineIndent = /^(\s+)/.exec(line)?.[1]?.length ?? 0
+```
+
+## Imports
+
+External dependencies first, then internal modules, separated by a blank line. Named imports with destructuring.
+
+```javascript
+import { Extension, Patch } from '@nejs/extension'
+
+import { Deferred } from './async/deferred.js'
+import { Callable } from './core/callable.js'
+import { Range } from './core/range.js'
+```
+
+## Blank Lines
+
+Use blank lines to separate logical sections within a function. One blank line between conceptual steps. Do not over-space — no double blank lines, no blank lines after opening braces or before closing braces.
+
+```javascript
+constructor(options) {
+  const config = (options && typeof(options) === 'object'
+    ? options
+    : {}
+  )
+
+  if (config?.resolve && config?.reject) {
+    throw new TypeError(
+      'resolve and reject options cannot be simultaneously provided'
+    )
+  }
+
+  let _resolve, _reject
+
+  super((resolve, reject) => {
+    _resolve = resolve
+    _reject = reject
+  })
+```
+
+## Class Structure
+
+Order within a class body:
+
+1. `#` private fields (with defaults)
+2. Public instance fields (with defaults)
+3. `constructor`
+4. Instance getters/setters
+5. Instance methods
+6. `Symbol`-keyed methods and getters (`Symbol.toPrimitive`, `Symbol.iterator`, `Symbol.toStringTag`, `Symbol.species`)
+7. Static getters (constants)
+8. Static methods
+
+```javascript
+export class Deferred extends Promise {
+  #promise = null
+  #reject = null
+  #resolve = null
+
+  value = null
+  reason = null
+
+  #settled = false
+
+  constructor(options) { ... }
+
+  get settled() { ... }
+  get promise() { ... }
+
+  resolve(value) { ... }
+  reject(reason) { ... }
+
+  static get [Symbol.species]() { ... }
+}
+```
+
+## Symbols
+
+Use `Symbol.for()` for shared/interoperable keys. Define symbol accessors as static getters with the `k` prefix convention.
+
+```javascript
+static get kHandler() {
+  return Symbol.for('callable.handler')
+}
+
+static get kFunction() {
+  return Symbol.for('callable.function')
+}
+```
+
+## String Concatenation
+
+Template literals for interpolation. The `+` operator is acceptable for simple one-off concatenation (e.g., `key + '.associated'`).
+
+## Trailing Commas
+
+Not enforced in either direction. Do not add them retroactively to existing code, do not remove them from existing code. When writing new multi-line object/array literals, trailing commas are acceptable.
+
+## Error Handling
+
+Throw specific error types (`TypeError`, `Error`) with descriptive string messages. For invalid input in utility/library code, prefer branching and returning a safe default over throwing.
+
+```javascript
+// throw for contract violations
+throw new TypeError(
+  'resolve and reject options cannot be simultaneously provided'
+)
+
+// branch for soft failures
+if (!this.isObject(obj)) {
+  console.warn('Object.add() must receive an object for `toObject`')
+  return obj
+}
+```

package/CODING_PHILOSOPHY.md

@@ -0,0 +1,36 @@
+# Coding Philosophy & Architectural Preferences
+
+Observations drawn from the `@nejs/foundation` and `@nejs/basic-extensions` codebases.
+
+## Core Beliefs
+
+**JavaScript maximalism.** The language's built-in types are *incomplete*, not broken. Rather than avoiding prototype modification, the approach is to build a reversible patch infrastructure (`@nejs/extension`) to do it correctly. The `Controls` system with enable/disable is a disciplined concession to orthodoxy — `arr.first` should just *work*.
+
+**Protocol-oriented thinking.** Heavy use of `Symbol.iterator`, `Symbol.species`, `Symbol.toPrimitive`, `Symbol.toStringTag`, and custom symbols throughout. Objects are participants in protocols. The `Callable` class is the clearest expression: a single entity that *is* both function and object, participating in both protocols simultaneously through comprehensive Proxy traps.
+
+**Expressiveness as a core value.** The `if*` conditional pattern on every type checker, the `is`/`has`/`as`/`si` global toolkit, the Deferred exposing resolve/reject — these convert imperative control flow into expressions. `si.array(val, transform, fallback)` over an if/else block. Functional programming flavor without dogma.
+
+**Descriptor-level awareness.** Properties are not key/value pairs — they are full descriptors with enumeration, configurability, and accessor semantics. Visibility handlers (`kMutablyHidden`, `kImmutablyVisible`), `Object.add()` with storage-backed accessors, and the `Descriptor` class form an entire vocabulary around `Object.defineProperty`.
+
+## Architecture Preferences
+
+**Bottom-up, layered abstraction.** `@nejs/extension` (patch mechanism) → `@nejs/basic-extensions` (enriched primitives) → `@nejs/foundation` (higher-level patterns). Each layer assumes the one below. The goal is not an application framework — it is building the *language you wish you had*, then writing applications in that language.
+
+**Enrich the base rather than wrap it.** Prefer extending built-in types with missing capabilities over creating parallel utility namespaces. Rich methods on every type (`set.map()`, `set.reduce()`, `arr.first`, `arr.last`) in the Ruby/Smalltalk tradition of making built-ins joyful to use.
+
+**Convention applied uniformly.** Every `isX` gets a corresponding `ifX`. Every type gets the same treatment. Patterns are systematic, not ad-hoc.
+
+## Implementation Conventions
+
+- `#` private fields over closures for encapsulation
+- Custom symbols (prefixed `k`) for internal access keys (`kHandler`, `kFunction`, `kDescriptorStore`)
+- Comprehensive JSDoc over TypeScript — types as documentation, not as a compilation step (tsc used as transpiler, not type checker)
+- Well-known Symbols implemented wherever semantically appropriate (`Symbol.iterator`, `Symbol.species`, `Symbol.toPrimitive`, `Symbol.toStringTag`)
+- Full Proxy trap coverage when proxying (not partial implementations)
+- Method chaining where it fits naturally (e.g., SemVer increment/decrement)
+
+## Influences
+
+- **Ruby/Smalltalk** — open classes, rich standard library methods on built-in types, ergonomic APIs
+- **jQuery** — deferred pattern, the philosophy that APIs should be ergonomic first
+- **JavaScript metaprogramming** — Proxy, Reflect, Symbol, and property descriptors are foundational tools, not curiosities

package/DOCUMENTATION_GUIDELINES.md

@@ -0,0 +1,221 @@
+# Documentation & Style Guidelines
+
+How documentation is written across `@nejs` projects. These aren't aspirational rules — they're patterns extracted from existing code. Follow them so that a reader who's seen three docs can predict the structure of the fourth.
+
+## Philosophy
+
+Code alone never captures intent and circumstance. Documentation exists to explain *why* something exists in the world, what design pressures shaped it, and what the reader should expect when they use it. The JSDoc is the primary type system — not TypeScript, not Flow — and it serves double duty: human-readable narrative *and* IDE-consumable type information (WebStorm, VS Code, etc.).
+
+TypeScript is avoided unless externally required. JSDoc `@param`, `@returns`, `@typedef`, and `@type` annotations carry the type information. This keeps the source as plain JavaScript while giving IDEs everything they need for autocomplete, hover docs, and type checking.
+
+## JSDoc Structure
+
+A complete doc block follows this order. Not every section appears on every method — scale detail to complexity.
+
+1. **Opening narrative** — What it does and *why it exists*. For classes, include historical context or lineage where relevant. For methods, lead with the practical purpose.
+2. **`@typedef` / `@callback`** — For complex option objects or function signatures, define them inline or reference a shared typedef. Use TypeScript-style interface notation inside fenced code blocks when the shape is complex.
+3. **`@param`** — Every parameter documented. Include union types with `|`, defaults with `[param=default]`, conditional requirements ("Required if `start` is a number"), and constraints ("Must be non-zero").
+4. **`@returns`** — What comes back and under what conditions.
+5. **`@throws`** — When and why.
+6. **`@example`** — Concrete, runnable scenarios (see Examples section below).
+
+### Simple methods get simple docs
+
+```javascript
+/**
+ * The `isString` method does exactly what one would expect. It returns
+ * true if the string matches typeof or instanceof as a string.
+ *
+ * @param {*} value checks to see if the `value` is a string
+ * @returns {boolean} `true` if it is a `String`, `false` otherwise
+ */
+```
+
+Three lines of description, one param, one return. Done.
+
+### Complex methods get structured docs
+
+For methods with multiple modes, option objects, or non-obvious behavior, use visual structure — tables, fenced code blocks for option lists, multiple examples showing different usage patterns:
+
+```javascript
+/**
+ * Applies Select Graphic Rendition (SGR) parameters to a given message
+ * for styling in terminal environments. This function allows for the
+ * dynamic styling of text output using ANSI escape codes.
+ *
+ * Colors:
+ * ```
+ * 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'
+ * ```
+ * Color Specifiers:
+ * ```
+ * 'fg' -> foreground  |  'bg' -> background  |  'bright' -> bright colors
+ * ```
+ *
+ * Modes:
+ * ```
+ * 'blink' or 'k' | 'conceal' or 'c' | 'italics' or 'i'  | 'strike' or 's'
+ * 'bold' or 'b'  | 'dim' or 'd'     | 'negative' or 'n' | 'underline' or 'u'
+ * ```
+ *
+ * @param {string} message The message to be styled.
+ * @param {...string} useModes Styling modes — colors, specifiers, and
+ * decorations. Can be combined in a single comma-separated string or
+ * passed as separate arguments.
+ * @returns {string} The styled string wrapped in ANSI escape codes.
+ *
+ * @example
+ * sgr('Hello', 'red')
+ * sgr('World', 'green,bold')
+ * sgr('Example', 'bluebgbright')
+ *
+ * // Shorthand syntax
+ * sgr('hello', 'biu')       // bold, italics, underline
+ * sgr('hello', 'bi,redfg')  // bold, italics, red foreground
+ */
+```
+
+## Examples
+
+Examples are stories, not syntax diagrams. Show a scenario the reader can inhabit.
+
+### Do this
+
+```javascript
+/**
+ * @example
+ * // assume this pure function exists someplace
+ * const lastThenFirstThenMiddle = function() {
+ *   let middle = ''
+ *
+ *   if (this.middleName)
+ *     middle = ` ${this.middleName}`
+ *
+ *   return `${this.lastName}, ${this.firstName}${middle}`
+ * }
+ *
+ * let people = []
+ * for await (const model of await getSomePeople()) {
+ *   let parseName = new Callable(model, lastThenFirstThenMiddle)
+ *   people.push(parseName())
+ * }
+ *
+ * console.log(people)
+ * // Might look like ['Doe, Jane', 'Smith, Sally Joanne']
+ */
+```
+
+This shows: the setup, the loop, the integration with async code, and what the output "might look like." The reader understands the *use case*, not just the constructor signature.
+
+### Teach through contrast
+
+When a method's behavior has meaningful boundaries, show both sides:
+
+```javascript
+/**
+ * @example
+ * // Note the differences between these
+ * const object = { get name() { return "Brie"; } };
+ * const descriptor = Object.getOwnPropertyDescriptor(object, 'name');
+ * is.callable(object);     // false
+ * is.callable(descriptor); // true
+ */
+```
+
+## Types in JSDoc
+
+JSDoc is the type system. Write types for the IDE, narrative for the human.
+
+### Primitives and unions
+
+```javascript
+@param {string|number} value
+@param {boolean} [inclusive=true]
+@param {*} value
+```
+
+### Complex option objects
+
+Use TypeScript-style interface notation inside the doc block when the shape warrants it:
+
+```javascript
+/**
+ * The constructor takes an object called `options`. It can have the
+ * following properties:
+ *
+ * ```
+ * interface BaseDeferredOptions {
+ *   // Deferreds store the value or reason. To turn this off, pass true
+ *   doNotTrackAnswers?: boolean;
+ * }
+ *
+ * interface DeferredResolveOptions extends BaseDeferredOptions {
+ *   resolve: any;     // Auto-resolve with this value
+ *   reject?: never;
+ * }
+ * ```
+ *
+ * @param {BaseDeferredOptions|DeferredResolveOptions} options
+ */
+```
+
+This gives the reader a typed shape to reference while keeping the source as plain JavaScript.
+
+### Callback signatures
+
+```javascript
+@param {function(number, number): boolean} compareFn
+@callback StepFunction
+@returns {number}
+```
+
+## Inline Comments
+
+### Explain decisions, not mechanics
+
+```javascript
+// If the target function is a big arrow function, convert it to
+// a bindable function. Note that big arrow functions will receive
+// the handler as its first parameter; so account for that.
+```
+
+This explains the *why* (arrow functions can't be bound) and the *consequence* (handler becomes first param). The code shows the *how*.
+
+### Be honest about shortcuts
+
+```javascript
+// being lazy here, someone has defined we make an accessor but
+// wants the default accessor behaviors with an associated store
+// made by us.
+```
+
+### Leave breadcrumbs for future you
+
+```javascript
+// NOTE to self; this is repeated here otherwise a circular reference from
+// Object<->Function<->Global occurs. See original source in global.this.js
+// {@see globalThis.isThenElse}
+```
+
+## Voice
+
+The documentation voice is **knowledgeable but approachable**. It's a teacher explaining to a smart student, not a reference manual reciting signatures.
+
+**Signature phrases** (use naturally, not mechanically):
+- "This is useful for scenarios where..."
+- "This allows..."
+- "Returns `true` if... `false` otherwise"
+- "If... is provided..."
+- "Optionally..."
+
+**Formatting conventions:**
+- Backticks around all code references in prose: `undefined`, `handler`, `Array.prototype`
+- `{@link ClassName}` for cross-references to other documented types
+- Periods at end of `@param` and `@returns` descriptions
+- Fenced code blocks inside JSDoc for visual structure (option tables, mode lists)
+
+## What Not to Document
+
+- Don't over-document the obvious. If the method is `isString` and it checks if something is a string, three lines suffice.
+- Don't repeat the function signature in prose. The params are already listed — the narrative should explain *intent*, not restate types.
+- Don't write generic advice ("always validate inputs"). Document what *this specific code* does and why.