@avstantso/utils-names-tree 1.2.1 → 1.3.2

package/README.md

@@ -14,6 +14,7 @@ Type-safe tree structure utilities for generating hierarchical names, paths, and
 - **Preset configurations** - Built-in presets for common use cases (Names, URLs, i18n keys)
 - **Customizable kinds** - Define custom formatting methods for different output types
 - **Tree merging** - Combine multiple data sources into a single tree structure
+- **Symbol-based root alias access** - Access `rootAlias` value via `NamesTree.symbolRootAlias` symbol, avoiding property name conflicts
 - **Prefix support** - Add prefixes to all generated values
 - Zero dependencies beyond the monorepo packages
 
@@ -40,9 +41,9 @@ import '@avstantso/utils-names-tree';
 
 // Use utilities from the global namespace
 const formTree = AVStantso.NamesTree.Names({
-  form: '',
-  label: '',
-  placeholder: ''
+  form: 1,
+  label: 1,
+  placeholder: 1
 });
 ```
 
@@ -55,9 +56,9 @@ import { NamesTree } from '@avstantso/utils-names-tree';
 
 // Use imported NamesTree namespace
 const formTree = NamesTree.Names({
-  form: '',
-  label: '',
-  placeholder: ''
+  form: 1,
+  label: 1,
+  placeholder: 1
 });
 
 console.log(`${formTree.label}`); // 'label'
@@ -65,6 +66,7 @@ console.log(`${formTree.label}`); // 'label'
 
 **Exported Members:**
 - `NamesTree` - Complete NamesTree utilities namespace (same as `AVStantso.NamesTree`)
+- `NamesTree.symbolRootAlias` - Symbol for accessing the `rootAlias` value from tree instances
 
 ## API Reference
 
@@ -94,11 +96,11 @@ import { NamesTree } from '@avstantso/utils-names-tree';
 
 const data = {
   user: {
-    profile: '',
-    settings: ''
+    profile: 1,
+    settings: 1
   },
   admin: {
-    dashboard: ''
+    dashboard: 1
   }
 };
 
@@ -116,37 +118,45 @@ console.log(tree.user.profile._path); // 'user/profile'
 
 ## Built-in Kinds
 
-NamesTree comes with several predefined kind methods that determine how tree paths are formatted.
-
-### `name`
-
-Returns the last segment of the path (leaf node name).
-
-**Example:** `['user', 'profile']` becomes `'profile'`
-
-### `path`
-
-Returns the full path with segments joined by `/`.
-
-**Example:** `['user', 'profile']` becomes `'user/profile'`
-
-### `url`
-
-Returns the full path as a URL with leading `/`.
-
-**Example:** `['user', 'profile']` becomes `'/user/profile'`
-
-### `i18n`
-
-Returns the full path with segments joined by `.` (dot notation).
-
-**Example:** `['schemas', 'login', 'required']` becomes `'schemas.login.required'`
-
-### `domain`
-
-Returns the full path with segments joined by `.` (same as i18n).
-
-**Example:** `['api', 'v1', 'users']` becomes `'api.v1.users'`
+NamesTree comes with 20+ predefined kind methods that determine how tree paths are formatted.
+
+### Basic Kinds
+
+| Kind | Separator | Example Input | Example Output |
+|------|-----------|---------------|----------------|
+| `name` | - | `['user', 'profile']` | `'profile'` |
+| `slash` / `path` | `/` | `['user', 'profile']` | `'user/profile'` |
+| `backslash` | `\` | `['user', 'profile']` | `'user\profile'` |
+| `dot` / `i18n` / `domain` | `.` | `['schemas', 'login']` | `'schemas.login'` |
+| `dash` | `-` | `['btn', 'primary']` | `'btn-primary'` |
+| `underscore` / `snake` | `_` | `['user', 'name']` | `'user_name'` |
+| `doubleColon` / `namespace` | `::` | `['std', 'vector']` | `'std::vector'` |
+| `colon` | `:` | `['a', 'b']` | `'a:b'` |
+| `arrow` | `->` | `['a', 'b']` | `'a->b'` |
+| `amp` | `&` | `['a', 'b']` | `'a&b'` |
+| `hash` | `#` | `['a', 'b']` | `'a#b'` |
+| `comma` / `csv` | `,` | `['a', 'b']` | `'a,b'` |
+| `semicolon` | `;` | `['a', 'b']` | `'a;b'` |
+| `space` / `title` | ` ` | `['hello', 'world']` | `'hello world'` |
+| `pipe` | `\|` | `['a', 'b']` | `'a\|b'` |
+
+### Derived Kinds (with prefixes/transformations)
+
+| Kind | Description | Example Input | Example Output |
+|------|-------------|---------------|----------------|
+| `url` | URL with leading `/` | `['user', 'profile']` | `'/user/profile'` |
+| `query` | Query string | `['a', 'b']` | `'?a&b'` |
+| `longArg` | CLI long argument | `['dry', 'run']` | `'--dry-run'` |
+| `shortArg` | CLI short argument | `['v']` | `'-v'` |
+| `envVar` | Environment variable | `['db', 'host']` | `'DB_HOST'` |
+| `cssClass` | CSS class selector | `['btn', 'primary']` | `'.btn-primary'` |
+| `cssId` | CSS ID selector | `['main', 'content']` | `'#main-content'` |
+| `anchor` | HTML anchor | `['section']` | `'#section'` |
+| `scoped` | Scoped package | `['org', 'pkg']` | `'@org/pkg'` |
+| `param` | Route parameter (last) | `['users', 'id']` | `':id'` |
+| `params` | Route parameters (all) | `['users', 'id']` | `':users/:id'` |
+| `arg` | Template arg (last) | `['users', 'id']` | `'{id}'` |
+| `args` | Template args (all) | `['users', 'id']` | `'{users}/{id}'` |
 
 ---
 
@@ -176,9 +186,9 @@ NamesTree.Names<T>(
 import { NamesTree } from '@avstantso/utils-names-tree';
 
 const form = {
-  form: '',
-  label: '',
-  placeholder: ''
+  form: 1,
+  label: 1,
+  placeholder: 1
 };
 
 const formTree = NamesTree.Names(form);
@@ -197,12 +207,12 @@ console.log(formDict); // { form: 'form', label: 'label', placeholder: 'placehol
 import { NamesTree } from '@avstantso/utils-names-tree';
 
 const form = {
-  form: '',
-  label: '',
-  placeholder: ''
+  form: 1,
+  label: 1,
+  placeholder: 1
 };
 
-const formTree = NamesTree.Names(form, { prefix: 'xxx-' });
+const formTree = NamesTree.Names(form, { prefix: 'xxx-' } as const);
 const formDict = formTree.Name;
 
 console.log(formDict);
@@ -272,12 +282,12 @@ import { NamesTree } from '@avstantso/utils-names-tree';
 const validationKeys = NamesTree.I18ns({
   user: {
     email: {
-      required: '',
-      invalid: ''
+      required: 1,
+      invalid: 1
     },
     password: {
-      required: '',
-      tooShort: ''
+      required: 1,
+      tooShort: 1
     }
   }
 });
@@ -318,15 +328,15 @@ import { NamesTree } from '@avstantso/utils-names-tree';
 
 const Urls = {
   profile: {
-    login: '',
-    logout: '',
-    settings: '',
-    registration: '',
-    reset: ''
+    login: 1,
+    logout: 1,
+    settings: 1,
+    registration: 1,
+    reset: 1
   },
   admin: {
-    roles: '',
-    users: ''
+    roles: 1,
+    users: 1
   }
 };
 
@@ -373,7 +383,7 @@ const Urls = { profile: { settings: '' } };
 const UrlsTree = NamesTree.Urls(Urls);
 
 // Get array of trees, one per kind
-const [NAMES, PATHS, URLS] = UrlsTree.splitted;
+const [NAMES, PATHS, URLS] = UrlsTree.$splitted;
 
 console.log(`${NAMES.profile.settings}`); // 'settings'
 console.log(NAMES.profile.settings); // 'settings'
@@ -385,17 +395,73 @@ console.log(`${URLS.profile.settings}`); // '/profile/settings'
 console.log(URLS.profile.settings); // '/profile/settings'
 ```
 
+**Using Root Alias:**
+```typescript
+import { NamesTree } from '@avstantso/utils-names-tree';
+
+const Urls = { profile: { settings: '' } };
+const UrlsTree = NamesTree.Urls(Urls, { rootAlias: 'Home' } as const);
+
+// Access root via alias
+console.log(`${UrlsTree.Home}`); // ''
+console.log(`${UrlsTree.Url.Home}`); // '/'
+
+// Splitted trees also have the alias
+const [NAMES, PATHS, URLS] = UrlsTree.$splitted;
+console.log(`${URLS.Home}`); // '/'
+
+// Access rootAlias value via Symbol (avoids property name conflicts)
+console.log(UrlsTree[NamesTree.symbolRootAlias]); // 'Home'
+```
+
+**Using Default Kind:**
+```typescript
+import { NamesTree } from '@avstantso/utils-names-tree';
+
+const data = { profile: { settings: '' } };
+
+// Default toString() uses first kind ('name')
+const tree1 = NamesTree(data, 'name', 'path', 'url');
+console.log(`${tree1.profile.settings}`); // 'settings'
+
+// Override default toString() to use 'url' kind
+const tree2 = NamesTree(data, { defaultKind: 'url' } as const, 'name', 'path', 'url');
+console.log(`${tree2.profile.settings}`); // '/profile/settings'
+```
+
+---
+
+### NamesTree.symbolRootAlias
+
+A Symbol property for safely accessing the `rootAlias` value from a tree instance. Using a Symbol avoids conflicts with tree data properties.
+
+**Type:** `typeof symbolRootAlias` (unique symbol)
+
+**Example:**
+```typescript
+import { NamesTree } from '@avstantso/utils-names-tree';
+
+const Urls = { profile: { settings: '' } };
+const UrlsTree = NamesTree.Urls(Urls, { rootAlias: 'Home' } as const);
+
+// Access rootAlias value via symbol
+console.log(UrlsTree[NamesTree.symbolRootAlias]); // 'Home'
+
+// The symbol is NOT accessible as a regular property
+console.log((UrlsTree as any).symbolRootAlias); // undefined
+```
+
 ---
 
 ## Advanced Features
 
 ### Tree Merging
 
-Combine multiple data sources into a single tree, useful for adding route handlers to URL structures.
+Combine multiple data sources into a single tree. Can be used for extending basic trees or adding route handlers to URL structures.
 
 **Method:**
 ```typescript
-tree.merge<M>(data: M): NamesTree<T & M, Kinds>
+tree.$merge<M>(data: M): NamesTree<T & M, Kinds>
 ```
 
 **Parameters:**
@@ -409,8 +475,8 @@ import { NamesTree } from '@avstantso/utils-names-tree';
 
 const Urls = {
   profile: {
-    login: '',
-    settings: ''
+    login: 1,
+    settings: 1
   }
 };
 
@@ -421,7 +487,7 @@ function profile() {
   return 123;
 }
 
-const merged = UrlsTree.merge({ profile });
+const merged = UrlsTree.$merge({ profile });
 
 // Call the function
 console.log(merged.profile()); // 123
@@ -439,9 +505,9 @@ import express from 'express';
 const routes = {
   api: {
     users: {
-      list: '',
-      create: '',
-      detail: ''
+      list: 1,
+      create: 1,
+      detail: 1
     }
   }
 };
@@ -456,7 +522,7 @@ const handlers = {
   }
 };
 
-const RoutesTree = NamesTree.Urls(routes).merge(handlers);
+const RoutesTree = NamesTree.Urls(routes).$merge(handlers);
 
 const app = express();
 
@@ -476,7 +542,7 @@ Extract individual trees for each kind from a multi-kind tree.
 
 **Property:**
 ```typescript
-tree.splitted: Array<NamesTree<T, [Kind]>>
+tree.$splitted: Array<NamesTree<T, [Kind]>>
 ```
 
 **Returns:** Array of single-kind trees in the order kinds were specified
@@ -485,10 +551,10 @@ tree.splitted: Array<NamesTree<T, [Kind]>>
 ```typescript
 import { NamesTree } from '@avstantso/utils-names-tree';
 
-const data = { user: { profile: '' } };
+const data = { user: { profile: 1 } };
 const tree = NamesTree.Urls(data);
 
-const [names, paths, urls] = tree.splitted;
+const [names, paths, urls] = tree.$splitted;
 
 console.log(`${names.user.profile}`); // 'profile'
 console.log(`${paths.user.profile}`); // 'user/profile'
@@ -514,34 +580,50 @@ NamesTree._RegKinds(kinds: Record<string, Kinds.Method>): void
 type Method = (path: string[], options?: Options) => string
 ```
 
+**TypeScript Support:**
+
+For proper type inference with custom kinds, extend the `KindsMeta` interface:
+
+```typescript
+declare global {
+  namespace AVStantso {
+    namespace NamesTree {
+      interface KindsMeta {
+        bem: '__';  // separator or KindMeta object
+      }
+    }
+  }
+}
+```
+
 **Example:**
 ```typescript
 import { NamesTree } from '@avstantso/utils-names-tree';
 
-// Register custom kind for CSS class names
+// Register custom kind for BEM-style CSS (block__element)
 NamesTree._RegKinds({
-  cssClass: (path, options) => {
+  bem: (path, options) => {
     const { prefix = '' } = options || {};
-    return `${prefix}${path.join('__')}`; // BEM-style
+    return `${prefix}${path.join('__')}`;
   }
 });
 
 // Use custom kind
 const components = {
   button: {
-    primary: '',
-    secondary: ''
+    icon: 1,
+    label: 1
   }
 };
 
-const cssTree = NamesTree(components, 'cssClass');
+const bemTree = NamesTree(components, 'bem');
 
-console.log(`${cssTree.button.primary}`); // 'button__primary'
-console.log(`${cssTree.button.secondary}`); // 'button__secondary'
+console.log(`${bemTree.button.icon}`); // 'button__icon'
+console.log(`${bemTree.button.label}`); // 'button__label'
 
 // With prefix
-const prefixedTree = NamesTree(components, { prefix: 'app-' }, 'cssClass');
-console.log(`${prefixedTree.button.primary}`); // 'app-button__primary'
+const prefixedTree = NamesTree(components, { prefix: 'app-' } as const, 'bem');
+console.log(`${prefixedTree.button.icon}`); // 'app-button__icon'
 ```
 
 **Example: GraphQL Field Paths**
@@ -556,9 +638,9 @@ NamesTree._RegKinds({
 
 const schema = {
   user: {
-    firstName: '',
-    lastName: '',
-    emailAddress: ''
+    firstName: 1,
+    lastName: 1,
+    emailAddress: 1
   }
 };
 
@@ -578,14 +660,37 @@ Union type for valid tree source data.
 
 **Type Definition:**
 ```typescript
-type Source = Source.Root | string
+type Source = TS.Type.Builtin  // string | number | boolean | null | undefined | symbol | bigint
 
 namespace Source {
   type Root = object | Function
 }
 ```
 
-**Description:** Tree sources can be nested objects, functions, or string values at leaf nodes.
+**Description:**
+- `Source` — any built-in primitive type for leaf nodes (values are ignored)
+- `Source.Root` — nested objects or functions for tree structure
+
+Leaf node values are ignored — only the object structure (keys) matters for generating paths.
+
+**Flexible Leaf Values:**
+```typescript
+// All of these are equivalent - leaf values are ignored
+const data1 = { user: { name: '' } };
+const data2 = { user: { name: 1 } };
+const data3 = { user: { name: true } };
+const data4 = { user: { name: null } };
+
+// Using numbers is shorter to type
+const form = {
+  form: 1,
+  label: 1,
+  placeholder: 1
+};
+
+const tree = NamesTree.Names(form);
+console.log(tree.Name); // { form: 'form', label: 'label', placeholder: 'placeholder' }
+```
 
 ---
 
@@ -610,11 +715,15 @@ Configuration options for tree creation.
 ```typescript
 interface Options {
   prefix?: string;
+  rootAlias?: string;
+  defaultKind?: Kind;
 }
 ```
 
 **Properties:**
 - `prefix` - Optional string to prepend to all generated values (default: `''`)
+- `rootAlias` - Optional alias for tree root as additional property (e.g., `'Home'` for URL trees). The alias is `enumerable: true`, so it appears in `Object.keys()` and iterations
+- `defaultKind` - Optional kind to use for default `toString()` output (defaults to first kind in tree)
 
 ---
 
@@ -626,17 +735,21 @@ Type-safe tree node structure.
 ```typescript
 type Node<
   T extends Source = Source,
+  O extends Options = Options,
   KDs extends readonly Kind[] = Kinds.All,
-  S extends boolean = false
-> = NodeKinds<KDs> & Node.Data<T, KDs, S>
+  S extends boolean = false,
+  P extends TS.Keys = []
+> = (S extends true ? unknown : _NodeKinds<O, KDs, P>) & Node.Data<T, O, KDs, S, P>
 ```
 
 **Type Parameters:**
 - `T` - Source data type
+- `O` - Options type (for prefix inference)
 - `KDs` - Tuple of kinds available on this node
-- `S` - If true, allows string tail nodes (for splitted trees)
+- `S` - If true, allows resolved string types for leaf nodes (for splitted trees)
+- `P` - Path stack for compile-time kind resolution
 
-**Description:** Represents a tree node with properties for data access and kind-specific formatters.
+**Description:** Represents a tree node with properties for data access and kind-specific formatters. The `P` parameter enables compile-time path tracking for precise type inference of kind accessors.
 
 ---
 
@@ -671,28 +784,56 @@ const urls = NamesTree.Urls(routeData);
 const urls = NamesTree(routeData, 'name', 'path', 'url');
 ```
 
-### 2. Leverage Type Inference
+### 2. Use Short Leaf Values
 
-Let TypeScript infer types from your data structure for full type safety.
+Leaf node values are ignored — use `1` or any short value instead of empty strings for brevity.
+
+```typescript
+// Verbose
+const form1 = { name: '', email: '', password: '' };
+
+// Concise - same result
+const form2 = { name: 1, email: 1, password: 1 };
+
+const tree = NamesTree.Names(form2);
+console.log(tree.Name); // { name: 'name', email: 'email', password: 'password' }
+```
+
+### 3. Leverage Type Inference
+
+TypeScript automatically infers key names as literal types — no `as const` needed for data structures.
 
 ```typescript
 const routes = {
-  admin: { users: '', roles: '' }
-} as const; // Use 'as const' for literal types
+  admin: { users: 1, roles: 1 }
+};
 
 const tree = NamesTree.Urls(routes);
 
 // TypeScript knows these properties exist
 tree.admin.users; // OK
 tree.admin.posts; // Error: Property 'posts' does not exist
+
+// Kind accessors have precise literal types
+tree.admin.users._url; // Type: '/admin/users'
 ```
 
-### 3. Use String Coercion for Output
+**Note:** Use `as const` for options when you need literal types:
+```typescript
+// Options need 'as const' for precise type inference
+const tree = NamesTree.Urls(data, { rootAlias: 'Home' } as const);
+tree.Home; // Property 'Home' exists
+
+const form = NamesTree.Names(data, { prefix: 'app-' } as const);
+form.Name.user; // Type: 'app-user'
+```
+
+### 4. Use String Coercion for Output
 
 Trees automatically convert to strings via `toString()` method.
 
 ```typescript
-const tree = NamesTree.Names({ user: '' });
+const tree = NamesTree.Names({ user: 1 });
 
 // Explicit string coercion
 console.log(`${tree.user}`); // 'user'
@@ -701,7 +842,7 @@ console.log(`${tree.user}`); // 'user'
 const url = `/api/${tree.user}`; // '/api/user'
 ```
 
-### 4. Centralize Route Definitions
+### 5. Centralize Route Definitions
 
 Define routes once and derive all variations from a single source.
 
@@ -709,15 +850,15 @@ Define routes once and derive all variations from a single source.
 // routes.ts
 export const RouteStructure = {
   auth: {
-    login: '',
-    logout: '',
-    register: ''
+    login: 1,
+    logout: 1,
+    register: 1
   },
   dashboard: {
-    home: '',
-    analytics: ''
+    home: 1,
+    analytics: 1
   }
-} as const;
+};
 
 export const Routes = NamesTree.Urls(RouteStructure);
 
@@ -734,17 +875,17 @@ router.get(`${Routes.Url.auth.login}`, loginHandler);
 fetch(`${Routes.Path.dashboard.home}`);
 ```
 
-### 5. Combine with Enums for Constants
+### 6. Combine with Enums for Constants
 
 Use trees for structured constants that need multiple representations.
 
 ```typescript
 const StatusStructure = {
-  pending: '',
-  active: '',
-  completed: '',
-  archived: ''
-} as const;
+  pending: 1,
+  active: 1,
+  completed: 1,
+  archived: 1
+};
 
 const StatusTree = NamesTree.Names(StatusStructure);
 
@@ -768,17 +909,17 @@ import { NamesTree } from '@avstantso/utils-names-tree';
 
 const AppRoutes = NamesTree.Urls({
   public: {
-    home: '',
-    about: '',
-    contact: ''
+    home: 1,
+    about: 1,
+    contact: 1
   },
   auth: {
-    login: '',
-    signup: ''
+    login: 1,
+    signup: 1
   },
   dashboard: {
-    overview: '',
-    settings: ''
+    overview: 1,
+    settings: 1
   }
 });
 
@@ -798,16 +939,16 @@ import { NamesTree } from '@avstantso/utils-names-tree';
 const i18nKeys = NamesTree.I18ns({
   common: {
     buttons: {
-      save: '',
-      cancel: '',
-      delete: ''
+      save: 1,
+      cancel: 1,
+      delete: 1
     }
   },
   errors: {
     validation: {
-      required: '',
-      email: '',
-      minLength: ''
+      required: 1,
+      email: 1,
+      minLength: 1
     }
   }
 });
@@ -823,11 +964,11 @@ t(`${i18nKeys.errors.validation.required}`); // 'errors.validation.required'
 import { NamesTree } from '@avstantso/utils-names-tree';
 
 const styles = NamesTree.Names({
-  button: '',
-  input: '',
-  label: '',
-  container: ''
-}, { prefix: 'app-' });
+  button: 1,
+  input: 1,
+  label: 1,
+  container: 1
+}, { prefix: 'app-' } as const);
 
 // Use in JSX
 <button className={styles.Name.button}>Click Me</button>
@@ -844,13 +985,13 @@ import { NamesTree } from '@avstantso/utils-names-tree';
 
 const FormFields = NamesTree.Names({
   user: {
-    firstName: '',
-    lastName: '',
-    email: '',
+    firstName: 1,
+    lastName: 1,
+    email: 1,
     address: {
-      street: '',
-      city: '',
-      zipCode: ''
+      street: 1,
+      city: 1,
+      zipCode: 1
     }
   }
 });
@@ -861,6 +1002,68 @@ const FormFields = NamesTree.Names({
 <input name={FormFields.Name.user.address.city} />
 ```
 
+### Environment Variables
+
+```typescript
+import { NamesTree } from '@avstantso/utils-names-tree';
+
+const envVars = NamesTree({
+  db: {
+    host: 1,
+    port: 1,
+    name: 1
+  },
+  api: {
+    key: 1,
+    secret: 1
+  }
+}, 'envVar');
+
+console.log(envVars.db.host._envVar); // 'DB_HOST'
+console.log(envVars.api.key._envVar); // 'API_KEY'
+```
+
+### CLI Arguments
+
+```typescript
+import { NamesTree } from '@avstantso/utils-names-tree';
+
+const cliArgs = NamesTree({
+  verbose: 1,
+  dry: { run: 1 },
+  output: { file: 1 }
+}, 'longArg', 'shortArg');
+
+console.log(cliArgs.verbose._longArg); // '--verbose'
+console.log(cliArgs.verbose._shortArg); // '-verbose'
+console.log(cliArgs.dry.run._longArg); // '--dry-run'
+```
+
+### Route Parameters
+
+```typescript
+import { NamesTree } from '@avstantso/utils-names-tree';
+
+const apiRoutes = NamesTree({
+  users: {
+    id: {
+      posts: {
+        postId: 1
+      }
+    }
+  }
+}, 'url', 'params', 'args');
+
+// Express-style route
+console.log(apiRoutes.users.id._params); // ':users/:id'
+
+// OpenAPI-style route
+console.log(apiRoutes.users.id.posts.postId._args); // '{users}/{id}/{posts}/{postId}'
+
+// Combined with url
+console.log(apiRoutes.users.id._url); // '/users/id'
+```
+
 ---
 
 ## Requirements