@homedev/framework 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -1,6 +1,123 @@
+/**
+ * Constructor for creating async functions dynamically from source code strings.
+ * Equivalent to the built-in async function constructor.
+ *
+ * @example
+ * ```typescript
+ * const fn = new AsyncFunction('x', 'y', 'return x + y')
+ * await fn(2, 3) // 5
+ * ```
+ */
 declare const AsyncFunction_2: any;
 export { AsyncFunction_2 as AsyncFunction }
 
+/**
+ * Guards against undefined and null values.
+ * Throws an error if the value is nullish, otherwise returns the value.
+ *
+ * @param value - The value to check
+ * @param message - Custom error message (default: 'Value is undefined')
+ * @returns The value if it is not nullish
+ * @throws {Error} When value is undefined or null
+ *
+ * @example
+ * ```typescript
+ * const value = defined(maybeUndefined, 'Required value missing')
+ * // value is guaranteed to be non-nullish here
+ *
+ * defined(0) // 0 (falsy but not nullish)
+ * defined(false) // false (falsy but not nullish)
+ * defined(null) // throws Error: Value is undefined
+ * ```
+ */
+declare function defined_2<T>(value: T | undefined | null, message?: string): T;
+export { defined_2 as defined }
+
+/**
+ * @public
+ */
+export declare type MergeMode = 'merge' | 'source' | 'target' | 'skip';
+
+/**
+ * @public
+ */
+export declare interface MergeOptions {
+    conflict?: (key: string, source: any, target: any, sourceContainer: any, targetContainer: any) => any;
+    mismatch?: (key: string, source: any, target: any, sourceContainer: any, targetContainer: any) => any;
+    navigate?: (key: string, source: any, target: any, sourceContainer: any, targetContainer: any) => boolean | undefined;
+    mode?: (key: string, source: any, target: any, sourceContainer: any, targetContainer: any) => MergeMode | void;
+}
+
+/**
+ * @public
+ */
+export declare enum NavigateAction {
+    Explore = 0,
+    SkipSiblings = 1,
+    NoExplore = 2,
+    ReplaceParent = 3,
+    DeleteParent = 4,
+    MergeParent = 5,
+    ReplaceItem = 6,
+    DeleteItem = 7
+}
+
+/**
+ * @public
+ */
+export declare type NavigateCallback = (context: NavigateContext) => Promise<NavigateResult> | NavigateResult;
+
+/**
+ * @public
+ */
+export declare interface NavigateContext {
+    key: string;
+    value: any;
+    path: string[];
+    parent: any;
+    parents: any[];
+}
+
+/**
+ * @public
+ */
+export declare class NavigateResult {
+    readonly action: NavigateAction;
+    by?: any | undefined;
+    skipSiblings?: boolean | undefined;
+    reexplore?: boolean | undefined;
+    constructor(action: NavigateAction, by?: any | undefined, skipSiblings?: boolean | undefined, reexplore?: boolean | undefined);
+    private static readonly _explore;
+    private static readonly _noExplore;
+    private static readonly _skipSiblings;
+    private static readonly _deleteParent;
+    static ReplaceParent(by: any, reexplore?: boolean): NavigateResult;
+    static SkipSiblings(): NavigateResult;
+    static Explore(): NavigateResult;
+    static NoExplore(): NavigateResult;
+    static DeleteParent(): NavigateResult;
+    static MergeParent(by: any): NavigateResult;
+    static ReplaceItem(by: any, skipSiblings?: boolean): NavigateResult;
+    static DeleteItem(skipSiblings?: boolean): NavigateResult;
+}
+
+/**
+ * Options for configuring the select function behavior
+ * @public
+ */
+export declare interface SelectOptions {
+    /** Value to set at the selected path */
+    set?: any;
+    /** Alternative key to use (currently unused) */
+    key?: string;
+    /** Path separator character (default: '.') */
+    separator?: string;
+    /** Default value to return when path is not found */
+    defaultValue?: any;
+    /** If true, returns undefined instead of throwing on missing paths */
+    optional?: boolean;
+}
+
 export { }
 
 
@@ -11,9 +128,11 @@ declare global {
     type MaybePromise<T> = T | Promise<T>;
     type AsyncFunction<T = any> = (...args: any[]) => Promise<T>;
     var AsyncFunction: typeof Function;
+    var defined: <T>(value: T | undefined | null, msg?: string) => T;
 }
 
 
+
 declare global {
     interface Array<T> {
         mapAsync<U>(callback: (value: T, index: number, array: T[]) => Promise<U>): Promise<U[]>;
@@ -29,28 +148,166 @@ declare global {
         findOrFail(predicate: (value: T, index: number, array: T[]) => boolean, message?: string, thisArg?: any): T;
         selectFor<K>(predicate: (value: T, index: number, array: T[]) => boolean, selector: (value: T) => K, message?: string, thisArg?: any): K;
         createInstances<TTarget>(targetConstructor: new (...args: any[]) => TTarget, ...args: any[]): TTarget[];
+        mergeAll(options?: MergeOptions): any;
     }
     interface ArrayConstructor {
         flat<T>(v: T | T[] | T[][]): T[];
     }
 }
 
-declare global {
-    interface String {
-        pascal(): string;
-        capital(): string;
-        camel(): string;
-        snake(separator: string): string;
-        kebab(): string;
-    }
-}
+
+
 
 declare global {
     interface ObjectConstructor {
         mapEntries<T extends object, U>(obj: T, callback: (key: keyof T, value: T[keyof T]) => [string | number | symbol, U]): Record<string | number | symbol, U>;
         toList<T extends object, U extends object, X extends string>(obj: T, key: X): (Record<X, string> & U)[];
         deepClone<T extends object>(obj: T): T;
-        find<T extends object, K extends keyof T>(obj: Record<string, T>, predicate: (value: T, key: string) => boolean): [K, T] | undefined;
-        findAll<T extends object, K extends keyof T>(obj: Record<string, T>, predicate: (value: T, key: string) => boolean): [K, T][];
+        merge(source: any, target: any, options?: MergeOptions): void;
+        navigate(o: any, cb: NavigateCallback): Promise<void>;
+        find(from: any, cb: (path: string, value: any) => boolean): Promise<any[]>;
+        select(from: any, path: string, options?: SelectOptions): any;
+    }
+}
+
+/**
+ * Guards against undefined and null values.
+ * Throws an error if the value is nullish, otherwise returns the value.
+ *
+ * @param value - The value to check
+ * @param message - Custom error message (default: 'Value is undefined')
+ * @returns The value if it is not nullish
+ * @throws {Error} When value is undefined or null
+ *
+ * @example
+ * ```typescript
+ * const value = defined(maybeUndefined, 'Required value missing')
+ * // value is guaranteed to be non-nullish here
+ *
+ * defined(0) // 0 (falsy but not nullish)
+ * defined(false) // false (falsy but not nullish)
+ * defined(null) // throws Error: Value is undefined
+ * ```
+ */
+/**
+ * Re-export AsyncFunction constructor from async module.
+ * Useful for dynamically creating async functions from source code strings.
+ *
+ * @example
+ * ```typescript
+ * const fn = new AsyncFunction('x', 'return x * 2')
+ * await fn(5) // 10
+ * ```
+ */
+
+declare global {
+    interface String {
+        capitalize(): string;
+        toPascal(): string;
+        toCamel(): string;
+        toSnake(): string;
+        toKebab(): string;
+        changeCase(to: 'upper' | 'lower' | 'pascal' | 'camel' | 'snake' | 'kebab'): string;
+        splitWithQuotes(separator?: string): {
+            value: string;
+            quoted: boolean;
+        }[];
+        splitNested(separator: string, open: string, close: string): string[];
+        padBlock(indent: number, separator?: string, padder?: string): string;
+        tokenize(from: Record<string, unknown>, tokenizer?: RegExp): string;
+        stripIndent(): string;
     }
 }
+
+
+
+/**
+ * @public
+ */
+    key: string;
+    value: any;
+    path: string[];
+    parent: any;
+    parents: any[];
+}
+/**
+ * @public
+ */
+    Explore = 0,
+    SkipSiblings = 1,
+    NoExplore = 2,
+    ReplaceParent = 3,
+    DeleteParent = 4,
+    MergeParent = 5,
+    ReplaceItem = 6,
+    DeleteItem = 7
+}
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+    readonly action: NavigateAction;
+    by?: any | undefined;
+    skipSiblings?: boolean | undefined;
+    reexplore?: boolean | undefined;
+    constructor(action: NavigateAction, by?: any | undefined, skipSiblings?: boolean | undefined, reexplore?: boolean | undefined);
+    private static readonly _explore;
+    private static readonly _noExplore;
+    private static readonly _skipSiblings;
+    private static readonly _deleteParent;
+    static ReplaceParent(by: any, reexplore?: boolean): NavigateResult;
+    static SkipSiblings(): NavigateResult;
+    static Explore(): NavigateResult;
+    static NoExplore(): NavigateResult;
+    static DeleteParent(): NavigateResult;
+    static MergeParent(by: any): NavigateResult;
+    static ReplaceItem(by: any, skipSiblings?: boolean): NavigateResult;
+    static DeleteItem(skipSiblings?: boolean): NavigateResult;
+}
+
+
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+    conflict?: (key: string, source: any, target: any, sourceContainer: any, targetContainer: any) => any;
+    mismatch?: (key: string, source: any, target: any, sourceContainer: any, targetContainer: any) => any;
+    navigate?: (key: string, source: any, target: any, sourceContainer: any, targetContainer: any) => boolean | undefined;
+    mode?: (key: string, source: any, target: any, sourceContainer: any, targetContainer: any) => MergeMode | void;
+}
+
+
+/**
+ * Options for configuring the select function behavior
+ * @public
+ */
+    /** Value to set at the selected path */
+    set?: any;
+    /** Alternative key to use (currently unused) */
+    key?: string;
+    /** Path separator character (default: '.') */
+    separator?: string;
+    /** Default value to return when path is not found */
+    defaultValue?: any;
+    /** If true, returns undefined instead of throwing on missing paths */
+    optional?: boolean;
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/index.js

@@ -1 +1,3 @@
-Array.prototype.mapAsync=async function(e){let r=[];for(let t=0;t<this.length;t++)r.push(await e(this[t],t,this));return r};Array.prototype.nonNullMap=function(e){let r=[];for(let t=0;t<this.length;t++){let n=e(this[t],t,this);if(n!=null)r.push(n)}return r};Array.prototype.nonNullMapAsync=async function(e){let r=[];for(let t=0;t<this.length;t++){let n=await e(this[t],t,this);if(n!=null)r.push(n)}return r};Array.prototype.sortBy=function(e,r=!0){return this.slice().sort((t,n)=>{let o=e(t),s=e(n);if(o<s)return r?-1:1;if(o>s)return r?1:-1;return 0})};Array.prototype.forEachAsync=async function(e){for(let r=0;r<this.length;r++)await e(this[r],r,this)};Array.prototype.unique=function(){return Array.from(new Set(this))};Array.prototype.uniqueBy=function(e){let r=new Set;return this.filter((t)=>{let n=e(t);if(r.has(n))return!1;else return r.add(n),!0})};Array.prototype.groupBy=function(e){return this.reduce((r,t)=>{let n=e(t);if(!r[n])r[n]=[];return r[n].push(t),r},{})};Array.prototype.toObject=function(e,r){return Object.fromEntries(this.map((t)=>{let n=e(t),o=r?r(t):t;return[n,o]}))};Array.prototype.toObjectWithKey=function(e){return Object.fromEntries(this.map((r)=>[String(r[e]),r]))};Array.prototype.findOrFail=function(e,r,t){let n=this.find(e,t);if(n===void 0)throw Error(r??"Element not found");return n};Array.prototype.selectFor=function(e,r,t,n){let o=this.find(e,n);if(o===void 0)throw Error(t??"Element not found");return r(o)};Array.flat=function(e){if(Array.isArray(e))return e.flat(2);else return[e]};Array.prototype.createInstances=function(e,...r){return this.map((t,n)=>new e(...r,t,n))};Object.mapEntries=function(e,r){let n=Object.entries(e).map(([o,s])=>r(o,s));return Object.fromEntries(n)};Object.toList=function(e,r){return Object.entries(e).map(([t,n])=>({[r]:t,...n}))};Object.deepClone=function(e){if(typeof structuredClone<"u")try{return structuredClone(e)}catch{}return JSON.parse(JSON.stringify(e))};Object.find=function(e,r){for(let t in e)if(Object.prototype.hasOwnProperty.call(e,t)){let n=e[t];if(n!==void 0&&r(n,t))return[t,n]}return};Object.findAll=function(e,r){let t=[];for(let n in e)if(Object.prototype.hasOwnProperty.call(e,n)){let o=e[n];if(o!==void 0&&r(o,n))t.push([n,o])}return t};global.AsyncFunction=Object.getPrototypeOf(async function(){}).constructor;String.prototype.pascal=function(){return this.replace(/((?:[_ ]+)\w|^\w)/g,(e,r)=>r.toUpperCase()).replace(/[_ ]/g,"")};String.prototype.capital=function(){return this.replace(/((?:[ ]+)\w|^\w)/g,(e,r)=>r.toUpperCase())};String.prototype.camel=function(){return this.pascal().replace(/((?:[ ]+\w)|^\w)/g,(e,r)=>r.toLowerCase())};String.prototype.snake=function(e){return this.replace(/([a-z])([A-Z])/g,`$1${e}$2`).replace(/\s+/g,e)};String.prototype.kebab=function(){return this.snake("-")};var c=Object.getPrototypeOf(async function(){}).constructor;export{c as AsyncFunction};
+Array.prototype.findOrFail=function(T,n,m){let r=this.find(T,m);if(r===void 0)throw Error(n??"Element not found");return r};Array.flat=function(T){if(Array.isArray(T))return T.flat(2);else return[T]};Array.prototype.forEachAsync=async function(T){for(let n=0;n<this.length;n++)await T(this[n],n,this)};Array.prototype.groupBy=function(T){return this.reduce((n,m)=>{let r=T(m);if(!n[r])n[r]=[];return n[r].push(m),n},{})};Array.prototype.createInstances=function(T,...n){return this.map((m,r)=>new T(...n,m,r))};Array.prototype.mapAsync=async function(T){return Promise.all(this.map(T))};Array.prototype.nonNullMap=function(T){let n=[];for(let m=0;m<this.length;m++){let r=T(this[m],m,this);if(r!=null)n.push(r)}return n};Array.prototype.nonNullMapAsync=async function(T){let n=[];for(let m=0;m<this.length;m++){let r=await T(this[m],m,this);if(r!=null)n.push(r)}return n};Array.prototype.mergeAll=function(T){let n={};for(let m of this.toReversed())Object.merge(m,n,T);return n};Array.prototype.toObject=function(T,n){return Object.fromEntries(this.map((m)=>{let r=T(m),f=n?n(m):m;return[r,f]}))};Array.prototype.toObjectWithKey=function(T){return Object.fromEntries(this.map((n)=>[String(n[T]),n]))};Array.prototype.selectFor=function(T,n,m,r){let f=this.find(T,r);if(f===void 0)throw Error(m??"Element not found");return n(f)};Array.prototype.sortBy=function(T,n=!0){return this.slice().sort((m,r)=>{let f=T(m),b=T(r);if(f<b)return n?-1:1;if(f>b)return n?1:-1;return 0})};Array.prototype.unique=function(){return Array.from(new Set(this))};Array.prototype.uniqueBy=function(T){let n=new Set;return this.filter((m)=>{let r=T(m);if(n.has(r))return!1;else return n.add(r),!0})};var y;((x)=>{x[x.Explore=0]="Explore";x[x.SkipSiblings=1]="SkipSiblings";x[x.NoExplore=2]="NoExplore";x[x.ReplaceParent=3]="ReplaceParent";x[x.DeleteParent=4]="DeleteParent";x[x.MergeParent=5]="MergeParent";x[x.ReplaceItem=6]="ReplaceItem";x[x.DeleteItem=7]="DeleteItem"})(y||={});class F{action;by;skipSiblings;reexplore;constructor(T,n,m,r){this.action=T;this.by=n;this.skipSiblings=m;this.reexplore=r}static _explore=new F(0);static _noExplore=new F(2);static _skipSiblings=new F(1);static _deleteParent=new F(4);static ReplaceParent(T,n){return new F(3,T,void 0,n)}static SkipSiblings(){return F._skipSiblings}static Explore(){return F._explore}static NoExplore(){return F._noExplore}static DeleteParent(){return F._deleteParent}static MergeParent(T){return new F(5,T)}static ReplaceItem(T,n){return new F(6,T,n)}static DeleteItem(T){return new F(7,void 0,T)}}Object.navigate=async(T,n)=>{let m=new WeakSet,r=[],f=[],b=async(o,x,E)=>{let O=o===null,A=O?F.Explore():await n({key:o,value:x,path:r,parent:E,parents:f});if(x&&typeof x==="object"&&A.action===0){if(m.has(x))return A;if(m.add(x),!O)r.push(o),f.push(E);let w=x;while(await d(w,o,E))w=E[o];if(!O)f.pop(),r.pop()}return A},d=async(o,x,E)=>{let O=Object.keys(o),U=O.length;for(let A=0;A<U;A++){let B=O[A],C=o[B],w=await b(B,C,o),K=w.action;if(K===0||K===2)continue;if(K===6){if(o[B]=w.by,w.skipSiblings)return;continue}if(K===7){if(delete o[B],w.skipSiblings)return;continue}if(K===1)return;if(K===3){if(x===null)throw Error("Cannot replace root object");if(E[x]=w.by,w.reexplore)return!0;return}if(K===4){if(x===null)throw Error("Cannot delete root object");delete E[x];return}if(K===5)delete o[B],Object.assign(o,w.by)}};await b(null,T,null)};Object.find=async function(T,n){let m=[];return await Object.navigate(T,(r)=>{if(n([...r.path,r.key].join("."),r.value))m.push(r.value);return F.Explore()}),m};Object.merge=(T,n,m)=>{for(let r of Object.keys(n)){if(T[r]===void 0)continue;let f=n[r],b=T[r];if(typeof b!==typeof f||Array.isArray(b)!==Array.isArray(f)){let o=m?.mismatch?.(r,b,f,T,n);if(o!==void 0){n[r]=o;continue}throw Error(`Type mismatch: ${r}`)}let d=m?.mode?.(r,b,f,T,n)??n[".merge"]??"merge";switch(d){case"source":n[r]=b;continue;case"target":continue;case"skip":delete n[r],delete T[r];continue;case"merge":break;default:throw Error(`Unknown merge mode: ${d}`)}if(typeof b==="object")if(Array.isArray(b))f.push(...b);else{if(m?.navigate?.(r,b,f,T,n)===!1)continue;Object.merge(b,f,m)}else{if(b===f)continue;let o=m?.conflict?.(r,b,f,T,n);n[r]=o===void 0?f:o}}for(let r of Object.keys(T))if(n[r]===void 0)n[r]=T[r]};var I=/^\[([^=\]]*)([=]*)([^\]]*)\]$/,X=/^([^[\]]*)\[([^\]]*)]$/,P=(T,n,m,r)=>{if(T.startsWith("{")&&T.endsWith("}")){let f=T.substring(1,T.length-1);return Object.select(n,f,m)?.toString()}return r?T:void 0},j=(T,n,m,r)=>{let f=P(n,m,r);if(f)return Object.select(T,f,r);let b=I.exec(n);if(b){let[,o,x,E]=b,O=P(o.trim(),m,r,!0),U=P(E.trim(),m,r,!0);if(Array.isArray(T)&&(x==="="||x==="==")&&O)return T.find((A)=>A?.[O]==U)}let d=X.exec(n);if(d){let[,o,x]=d;return T?.[o]?.[x]}return T?.[n]};Object.select=(T,n,m)=>{let r=void 0,f=void 0,b=n??"",d=(U)=>{if(!U)return[U,!1];return U.endsWith("?")?[U.substring(0,U.length-1),!0]:[U,!1]},o=(U,A)=>{let[B,C]=d(A.pop());if(!B){if(m?.set!==void 0&&f!==void 0&&r!==void 0)r[f]=m.set;return U}let w=j(U,B,T,m);if(w===void 0){if(C||m?.optional||m?.defaultValue!==void 0)return;throw Error(`Unknown path element: "${B}" in "${b}"`)}return r=U,f=B,o(w,A)},x=b.splitNested(m?.separator??".","{","}"),E=void 0;if(x.length>0&&x[x.length-1].startsWith("?="))E=x.pop()?.substring(2);x.reverse();let O=o(T,x);if(O===void 0)return E??m?.defaultValue;return O};Object.deepClone=function(T){if(typeof structuredClone<"u")try{return structuredClone(T)}catch{}return JSON.parse(JSON.stringify(T))};Object.toList=function(T,n){return Object.entries(T).map(([m,r])=>({[n]:m,...r}))};Object.mapEntries=function(T,n){let r=Object.entries(T).map(([f,b])=>n(f,b));return Object.fromEntries(r)};global.AsyncFunction=Object.getPrototypeOf(async function(){}).constructor;global.defined=(T,n="Value is undefined")=>{if(T===void 0||T===null)throw Error(n);return T};String.prototype.tokenize=function(T,n=/\${([^}]+)}/g){return this.replace(n,(m,r)=>{let f=T[r];if(f===null||f===void 0)return"";if(typeof f==="string")return f;if(typeof f==="number"||typeof f==="boolean")return String(f);return String(f)})};String.prototype.toPascal=function(){return this.replace(/((?:[_ ]+)\w|^\w)/g,(T,n)=>n.toUpperCase()).replace(/[_ ]/g,"")};String.prototype.capitalize=function(){return this.replace(/((?:[ ]+)\w|^\w)/g,(T,n)=>n.toUpperCase())};String.prototype.toCamel=function(){return this.toPascal().replace(/((?:[ ]+\w)|^\w)/g,(T,n)=>n.toLowerCase())};String.prototype.toSnake=function(){return this.replace(/([a-z])([A-Z])/g,"$1_$2").replace(/\s+/g,"_")};String.prototype.toKebab=function(){return this.replace(/([a-z])([A-Z])/g,"$1-$2").replace(/\s+/g,"-")};String.prototype.changeCase=function(T){switch(T){case"upper":return this.toUpperCase();case"lower":return this.toLowerCase();case"pascal":return this.toPascal();case"camel":return this.toCamel();case"snake":return this.toSnake();case"kebab":return this.toKebab();default:throw Error(`Unsupported case type: ${T}`)}};String.prototype.splitWithQuotes=function(T=","){let n=[],m=this.length,r=T.length,f=0,b=(d)=>{if(d+r>m)return!1;for(let o=0;o<r;o++)if(this[d+o]!==T[o])return!1;return!0};while(f<m){while(f<m&&this[f]===" ")f++;if(f>=m)break;let d="",o=this[f]==='"'||this[f]==="'";if(o){let x=this[f++];while(f<m&&this[f]!==x)d+=this[f++];if(f<m)f++}else{while(f<m&&!b(f)){let x=this[f];if(x==='"'||x==="'"){d+=x,f++;while(f<m&&this[f]!==x)d+=this[f++];if(f<m)d+=this[f++]}else d+=this[f++]}d=d.trim()}if(d)n.push({value:d,quoted:o});if(b(f))f+=r}return n};String.prototype.splitNested=function(T,n,m){let r=0,f="",b=[];for(let d of this){if(f+=d,d===n)r++;if(d===m)r--;if(r===0&&d===T)b.push(f.slice(0,-1)),f=""}if(f)b.push(f);return b};String.prototype.padBlock=function(T,n=`
+`,m=" "){let r=m.repeat(T);return this.split(n).map((f)=>r+f).join(n)};String.prototype.stripIndent=function(){let T=this.split(/\r?\n/),n=T.filter((r)=>r.trim().length>0).map((r)=>/^[ \t]*/.exec(r)?.[0].length??0),m=n.length>0?Math.min(...n):0;if(m===0)return this;return T.map((r)=>r.slice(m)).join(`
+`)};var W=Object.getPrototypeOf(async function(){}).constructor;function i(T,n="Value is undefined"){if(T===void 0||T===null)throw Error(n);return T}export{i as defined,F as NavigateResult,y as NavigateAction,W as AsyncFunction};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homedev/framework",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "homedev framework",
   "author": "julzor",
   "license": "ISC",