@rnzeus/atlas 0.1.0

package/dist/services/navigation/service.d.ts

@@ -0,0 +1,55 @@
+import type { LinkingOptions, NavigationContainerRef, ParamListBase } from '@react-navigation/native';
+import type { BuiltPath, NavigationOnError, NavigationStrict, QueryOptions, RouteDef, RouteParams, RouteQuery } from '../../config/internal';
+import type { NavLike } from './types';
+declare class NavService<T extends ParamListBase = ParamListBase> {
+    private ref?;
+    private linking?;
+    /** strict mode (boolean) */
+    strict: NavigationStrict;
+    /** error handler (optional) */
+    onError?: NavigationOnError;
+    set navRef(ref: NavigationContainerRef<T>);
+    set linkingConfig(linking: LinkingOptions<T>);
+    get navRef(): NavigationContainerRef<T>;
+    private meta;
+    private brandPath;
+    private getRouteFromPath;
+    private handleValidationError;
+    private normalizeBuild;
+    private normalizeQuery;
+    private ensureRefReady;
+    private ensureLinking;
+    private last;
+    private getLeafFromState;
+    private parsePath;
+    private buildNestedNavigate;
+    private ensureAtParents;
+    private findNavigatorKeyByName;
+    private getStackStateByName;
+    private getCurrentStackKey;
+    private pushOrReplace;
+    private hasRoute;
+    private routeTreeHasLeaf;
+    private buildParamsFromChain;
+    navigate: (path: BuiltPath, navigation?: NavLike) => void;
+    push: (path: BuiltPath) => void;
+    replace: (path: BuiltPath) => void;
+    popTo: (path: BuiltPath, navigation?: NavLike) => void;
+    navigateUnsafe: (path: string, navigation?: NavLike) => void;
+    pushUnsafe: (path: string) => void;
+    replaceUnsafe: (path: string) => void;
+    popToTop: (navigation?: NavLike) => void;
+    popToUnsafe: (path: string, navigation?: NavLike) => void;
+    goBack: () => void;
+    reset: (path: BuiltPath) => void;
+    resetUnsafe: (path: string) => void;
+    getCurrentPath: () => string;
+    build<R extends RouteDef<undefined, any>>(route: R): BuiltPath<R>;
+    build<R extends RouteDef<Record<string, string | number>, any>>(route: R, params: RouteParams<R>): BuiltPath<R>;
+    private safeJsonStringify;
+    query<R extends RouteDef<any, undefined>>(url: BuiltPath<R>): BuiltPath<R>;
+    query<R extends RouteDef<any, undefined>>(url: BuiltPath<R>, q: undefined, opts?: QueryOptions): BuiltPath<R>;
+    query<R extends RouteDef<any, any>>(url: BuiltPath<R>, q: RouteQuery<R>, opts?: QueryOptions): BuiltPath<R>;
+}
+declare const _default: NavService<ParamListBase>;
+export default _default;

package/dist/services/navigation/service.js

@@ -0,0 +1,536 @@
+import { CommonActions, getPathFromState, getStateFromPath, StackActions } from '@react-navigation/native';
+class NavService {
+    constructor() {
+        /** strict mode (boolean) */
+        this.strict = false;
+        // ───────────────── strict helpers ─────────────────
+        this.meta = new WeakMap();
+        // ───────────── public API (safe) ─────────────
+        this.navigate = (path, navigation) => {
+            this.navigateUnsafe(path, navigation);
+        };
+        this.push = (path) => {
+            this.pushUnsafe(path);
+        };
+        this.replace = (path) => {
+            this.replaceUnsafe(path);
+        };
+        this.popTo = (path, navigation) => {
+            this.popToUnsafe(path, navigation);
+        };
+        // ───────────── public API (unsafe) ─────────────
+        this.navigateUnsafe = (path, navigation) => {
+            if (!this.ensureLinking())
+                return;
+            if (navigation) {
+                const parsed = this.parsePath(path);
+                if (!parsed)
+                    return;
+                const { parents, leaf } = parsed;
+                navigation.dispatch(this.buildNestedNavigate(parents, leaf));
+                return;
+            }
+            if (!this.ensureRefReady())
+                return;
+            const parsed = this.parsePath(path);
+            if (!parsed)
+                return;
+            const { parents, leaf } = parsed;
+            this.ensureAtParents(parents);
+            const parent = this.last(parents);
+            if (!parent)
+                return;
+            const targetKey = this.findNavigatorKeyByName(parent);
+            const stackState = this.getStackStateByName(parent);
+            if (!targetKey || !stackState) {
+                this.ref?.dispatch(this.buildNestedNavigate(parents, leaf));
+                return;
+            }
+            const routes = stackState.routes ?? [];
+            const existingIndex = routes.findIndex(r => r.name === leaf.name);
+            if (existingIndex >= 0) {
+                const count = routes.length - 1 - existingIndex;
+                if (count > 0)
+                    this.ref?.dispatch({ ...StackActions.pop(count), target: targetKey });
+                if (leaf.params && Object.keys(leaf.params).length > 0) {
+                    this.ref?.dispatch(CommonActions.setParams({
+                        params: leaf.params,
+                        target: routes[existingIndex].key,
+                    }));
+                }
+            }
+            else {
+                this.ref?.dispatch({ ...StackActions.push(leaf.name, leaf.params), target: targetKey });
+            }
+        };
+        this.pushUnsafe = (path) => {
+            this.pushOrReplace('push', path);
+        };
+        this.replaceUnsafe = (path) => {
+            this.pushOrReplace('replace', path);
+        };
+        this.popToTop = (navigation) => {
+            if (navigation) {
+                navigation.dispatch(StackActions.popToTop());
+                return;
+            }
+            if (!this.ensureRefReady())
+                return;
+            const targetKey = this.getCurrentStackKey();
+            if (!targetKey)
+                return;
+            this.ref?.dispatch({ ...StackActions.popToTop(), target: targetKey });
+        };
+        this.popToUnsafe = (path, navigation) => {
+            if (!this.ensureLinking())
+                return;
+            const parsed = this.parsePath(path);
+            if (!parsed)
+                return;
+            const { parents, leaf } = parsed;
+            const targetChain = [...parents, leaf.name];
+            if (navigation) {
+                const navs = [];
+                let n = navigation;
+                while (n) {
+                    navs.push(n);
+                    n = n.getParent?.();
+                    if (!n)
+                        break;
+                }
+                const navChain = [...navs].reverse();
+                const activeState = navChain[navChain.length - 1]?.getState?.();
+                if (this.hasRoute(activeState, leaf.name)) {
+                    const deepNav = navChain[navChain.length - 1];
+                    if (typeof deepNav.popTo === 'function') {
+                        deepNav.popTo(leaf.name);
+                    }
+                    else {
+                        const routes = activeState?.routes ?? [];
+                        const idx = routes.findIndex(r => r.name === leaf.name);
+                        const count = idx >= 0 ? routes.length - 1 - idx : 0;
+                        if (count > 0)
+                            navigation.dispatch(StackActions.pop(count));
+                        if (leaf.params && Object.keys(leaf.params).length) {
+                            navigation.dispatch(CommonActions.setParams({ params: leaf.params }));
+                        }
+                    }
+                    return;
+                }
+                let chosenLevel = -1;
+                for (let j = targetChain.length - 1; j >= 0; j--) {
+                    const navAtLevel = navChain[j];
+                    const stateAtLevel = navAtLevel?.getState?.();
+                    const targetName = targetChain[j];
+                    if (targetName && this.hasRoute(stateAtLevel, targetName)) {
+                        chosenLevel = j;
+                        break;
+                    }
+                }
+                if (chosenLevel >= 0) {
+                    const navAtLevel = navChain[chosenLevel];
+                    const stateAtLevel = navAtLevel?.getState?.();
+                    const routes = stateAtLevel?.routes ?? [];
+                    const idx = routes.findIndex(r => r.name === targetChain[chosenLevel]);
+                    const count = idx >= 0 ? routes.length - 1 - idx : 0;
+                    if (count > 0)
+                        navAtLevel.dispatch(StackActions.pop(count));
+                    const remainder = targetChain.slice(chosenLevel + 1, targetChain.length - 1);
+                    const nestedParams = this.buildParamsFromChain(remainder, leaf);
+                    if (typeof navAtLevel.popTo === 'function') {
+                        navAtLevel.popTo(targetChain[chosenLevel], nestedParams);
+                    }
+                    else {
+                        navAtLevel.dispatch(CommonActions.navigate({ name: targetChain[chosenLevel] || '', params: nestedParams }));
+                    }
+                    return;
+                }
+                navigation.dispatch(this.buildNestedNavigate(parents, leaf));
+                return;
+            }
+            if (!this.ensureRefReady())
+                return;
+            const chain = [];
+            let s = this.ref?.getRootState();
+            let k = s?.key;
+            while (s) {
+                chain.push({ state: s, key: k });
+                const r = s.routes?.[s.index ?? 0];
+                if (!r?.state)
+                    break;
+                s = r.state;
+                k = s?.key ?? k;
+            }
+            const deepest = chain[chain.length - 1];
+            if (this.hasRoute(deepest?.state, leaf.name)) {
+                const routes = deepest?.state?.routes ?? [];
+                const idx = routes.findIndex(r => r.name === leaf.name);
+                const count = idx >= 0 ? routes.length - 1 - idx : 0;
+                if (count > 0 && deepest?.key) {
+                    this.ref?.dispatch({ ...StackActions.pop(count), target: deepest.key });
+                }
+                return;
+            }
+            let chosenLevel = -1;
+            for (let j = targetChain.length - 1; j >= 0; j--) {
+                const st = chain[j]?.state;
+                const targetName = targetChain[j];
+                if (targetName && this.hasRoute(st, targetName)) {
+                    chosenLevel = j;
+                    break;
+                }
+            }
+            if (chosenLevel >= 0) {
+                const level = chain[chosenLevel];
+                const routes = level?.state?.routes ?? [];
+                const idx = routes.findIndex(r => r.name === targetChain[chosenLevel]);
+                const count = idx >= 0 ? routes.length - 1 - idx : 0;
+                if (count > 0 && level?.key) {
+                    this.ref?.dispatch({ ...StackActions.pop(count), target: level.key });
+                }
+                const routeObj = routes[idx];
+                if (this.routeTreeHasLeaf(routeObj, leaf.name))
+                    return;
+                const remainder = targetChain.slice(chosenLevel + 1, targetChain.length - 1);
+                const nestedParams = this.buildParamsFromChain(remainder, leaf);
+                this.ref?.dispatch(CommonActions.navigate({
+                    name: targetChain[chosenLevel] || '',
+                    params: nestedParams,
+                }));
+                return;
+            }
+            this.ref?.dispatch(this.buildNestedNavigate(parents, leaf));
+        };
+        this.goBack = () => {
+            if (!this.ensureRefReady())
+                return;
+            if (this.ref?.canGoBack?.())
+                this.ref.goBack();
+        };
+        this.reset = (path) => {
+            this.resetUnsafe(path);
+        };
+        this.resetUnsafe = (path) => {
+            if (!this.ensureRefReady() || !this.ensureLinking())
+                return;
+            const opts = this.linking?.config;
+            const state = getStateFromPath(path, opts);
+            if (state)
+                this.ref?.reset(state);
+        };
+        this.getCurrentPath = () => {
+            const state = this.ref?.getRootState();
+            if (!this.ensureRefReady() || !this.ensureLinking() || !state)
+                return '';
+            const opts = this.linking?.config;
+            return getPathFromState(state, opts) ?? '';
+        };
+    }
+    set navRef(ref) {
+        this.ref = ref;
+    }
+    set linkingConfig(linking) {
+        this.linking = linking;
+    }
+    get navRef() {
+        return this.ref;
+    }
+    brandPath(value, route) {
+        const boxed = new String(value);
+        this.meta.set(boxed, route);
+        return boxed;
+    }
+    getRouteFromPath(url) {
+        return this.meta.get(url);
+    }
+    handleValidationError(error, ctx) {
+        try {
+            this.onError?.(error, ctx);
+        }
+        catch {
+            // ignore
+        }
+        if (this.strict) {
+            throw error;
+        }
+        // non-strict: do not throw
+        console.warn(error.message);
+    }
+    normalizeBuild(route, params) {
+        const schema = route.paramsSchema;
+        if (!schema)
+            return params;
+        const res = schema.safeParse(params);
+        if (res.success)
+            return res.data;
+        this.handleValidationError(new Error(`[NavService] build(${route.path}) invalid: ${String(res.error?.message ?? '')}`), { type: 'build', route, input: params });
+        return params;
+    }
+    normalizeQuery(route, query) {
+        const schema = route.querySchema;
+        if (!schema)
+            return query;
+        const res = schema.safeParse(query);
+        if (res.success)
+            return res.data;
+        this.handleValidationError(new Error(`[NavService] query(${route.path}) invalid: ${String(res.error?.message ?? '')}`), { type: 'query', route, input: query });
+        return query;
+    }
+    // ───────────────── guards ─────────────────
+    ensureRefReady() {
+        if (!this.ref) {
+            console.warn('[NavService] navRef is not set. Call setRef(ref) or pass local navigation.');
+            return false;
+        }
+        if (!this.ref?.isReady?.()) {
+            console.warn('[NavService] navRef is not ready yet.');
+            return false;
+        }
+        return true;
+    }
+    ensureLinking() {
+        if (!this.linking?.config) {
+            console.warn('[NavService] linking is not set. Call NavService.linking = linking.');
+            return false;
+        }
+        return true;
+    }
+    // ───────────────── utils ─────────────────
+    last(arr) {
+        return arr[arr.length - 1];
+    }
+    getLeafFromState(state) {
+        let s = state;
+        const parents = [];
+        while (s?.routes?.[s.index ?? 0]?.state) {
+            const r = s.routes[s.index ?? 0];
+            parents.push(r.name);
+            s = r.state;
+        }
+        const leaf = s.routes[s.index ?? 0];
+        return { parents, leaf };
+    }
+    parsePath(path) {
+        if (!this.ensureLinking())
+            return;
+        const opts = this.linking?.config;
+        const state = getStateFromPath(path, opts);
+        if (!state)
+            return;
+        return this.getLeafFromState(state);
+    }
+    buildNestedNavigate(parents, leaf) {
+        const payload = parents.reduceRight((child, parent) => ({
+            name: parent,
+            params: { screen: child.name, params: child.params },
+        }), { name: leaf.name, params: leaf.params });
+        return CommonActions.navigate(payload);
+    }
+    ensureAtParents(parentNames) {
+        if (!this.ref || !this.ref.isReady?.() || parentNames.length === 0)
+            return;
+        let action = undefined;
+        for (let i = parentNames.length - 1; i >= 0; i--) {
+            action = {
+                type: CommonActions.navigate('').type,
+                payload: {
+                    name: parentNames[i],
+                    params: action ? { screen: action.payload.name, params: action.payload.params } : undefined,
+                },
+            };
+        }
+        if (action)
+            this.ref.dispatch(action);
+    }
+    findNavigatorKeyByName(name) {
+        if (!name || !this.ref?.getRootState)
+            return;
+        const walk = (state) => {
+            if (!state)
+                return;
+            const current = state.routes[state.index ?? 0];
+            if (current?.name === name && current?.state?.key)
+                return current.state.key;
+            for (const r of state.routes) {
+                const k = walk(r.state);
+                if (k)
+                    return k;
+            }
+            return;
+        };
+        return walk(this.ref.getRootState());
+    }
+    getStackStateByName(name) {
+        if (!name || !this.ref?.getRootState)
+            return;
+        const walk = (state) => {
+            if (!state)
+                return;
+            const current = state.routes[state.index ?? 0];
+            if (current?.name === name && current?.state)
+                return current.state;
+            for (const r of state.routes) {
+                const s = walk(r.state);
+                if (s)
+                    return s;
+            }
+        };
+        return walk(this.ref.getRootState());
+    }
+    getCurrentStackKey() {
+        if (!this.ref?.getRootState)
+            return;
+        let s = this.ref.getRootState();
+        let lastKey = s?.key;
+        while (s?.routes?.[s.index ?? 0]?.state) {
+            s = s.routes[s.index ?? 0].state;
+            if (s?.key)
+                lastKey = s.key;
+        }
+        return lastKey;
+    }
+    pushOrReplace(kind, path) {
+        if (!this.ensureRefReady() || !this.ensureLinking())
+            return;
+        const parsed = this.parsePath(path);
+        if (!parsed)
+            return;
+        const { parents, leaf } = parsed;
+        this.ensureAtParents(parents);
+        const parent = this.last(parents);
+        if (!parent)
+            return;
+        const targetKey = this.findNavigatorKeyByName(parent);
+        if (!targetKey) {
+            this.ref?.dispatch(this.buildNestedNavigate(parents, leaf));
+            return;
+        }
+        const action = kind === 'push' ? StackActions.push(leaf.name, leaf.params) : StackActions.replace(leaf.name, leaf.params);
+        this.ref?.dispatch({ ...action, target: targetKey });
+    }
+    // ───────────── helpers for popTo ─────────────
+    hasRoute(state, name) {
+        const routes = state?.routes ?? [];
+        return routes.some(r => r.name === name);
+    }
+    routeTreeHasLeaf(route, leafName) {
+        let s = route?.state;
+        while (s?.routes) {
+            const cur = s.routes[s.index ?? 0];
+            if (!cur)
+                break;
+            if (cur.name === leafName)
+                return true;
+            s = cur.state;
+        }
+        return false;
+    }
+    buildParamsFromChain(chainBelow, leaf) {
+        return chainBelow.reduceRight((child, parent) => ({ screen: parent, params: child }), leaf.params ? { screen: leaf.name, params: leaf.params } : { screen: leaf.name });
+    }
+    build(route, params) {
+        const normalized = params == null ? undefined : this.normalizeBuild(route, params);
+        const template = route.path;
+        if (normalized == null)
+            return this.brandPath(template, route);
+        const out = Object.entries(normalized).reduce((acc, [k, v]) => acc.replace(`:${k}`, encodeURIComponent(String(v))), template);
+        return this.brandPath(out, route);
+    }
+    safeJsonStringify(value) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    query(url, q, opts) {
+        if (q == null)
+            return url;
+        const route = this.getRouteFromPath(url);
+        const normalized = route ? this.normalizeQuery(route, q) : q;
+        const encode = opts?.encode ?? true;
+        const nested = opts?.nested ?? 'json';
+        const debug = opts?.debug ?? false;
+        const nullable = opts?.nullable ?? false;
+        const clean = (value) => {
+            if (value === undefined)
+                return undefined;
+            if (value === null)
+                return nullable ? null : undefined;
+            if (typeof value === 'string' && value.length === 0)
+                return undefined;
+            if (Array.isArray(value)) {
+                const arr = value.map(clean).filter(v => v !== undefined);
+                return arr.length ? arr : undefined;
+            }
+            if (typeof value === 'object') {
+                const obj = {};
+                for (const [k, v] of Object.entries(value)) {
+                    const cleaned = clean(v);
+                    if (cleaned !== undefined)
+                        obj[k] = cleaned;
+                }
+                return Object.keys(obj).length ? obj : undefined;
+            }
+            return value;
+        };
+        const [beforeHash, hashRest] = url.split('#', 2);
+        const hash = hashRest !== undefined ? `#${hashRest}` : '';
+        const [base, searchRest] = beforeHash?.split('?', 2) ?? [];
+        const existingQuery = (searchRest ? Object.fromEntries(new URLSearchParams(searchRest)) : {});
+        const merged = { ...existingQuery, ...normalized };
+        const cleaned = clean(merged) ?? {};
+        if (debug) {
+            console.groupCollapsed('Navigation.query[debug]');
+            console.log('base:', base);
+            console.log('existing query:', existingQuery);
+            console.log('input query:', normalized);
+            console.log('merged query:', merged);
+            console.log('cleaned query:', cleaned);
+            console.log('nested:', nested, 'encode:', encode);
+            console.groupEnd();
+        }
+        const params = new URLSearchParams();
+        const pushParam = (key, value) => {
+            if (value === undefined)
+                return;
+            // arrays
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    pushParam(key, item);
+                return;
+            }
+            // null (optional)
+            if (value === null) {
+                params.append(key, 'null');
+                return;
+            }
+            // plain objects → JSON
+            if (typeof value === 'object' && value !== null) {
+                const json = this.safeJsonStringify(value);
+                if (json !== undefined)
+                    params.append(key, json);
+                return;
+            }
+            // primitives only
+            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                params.append(key, String(value));
+                return;
+            }
+        };
+        for (const [k, v] of Object.entries(cleaned)) {
+            pushParam(k, v);
+        }
+        let queryString = params.toString();
+        if (!encode && queryString) {
+            queryString = decodeURIComponent(queryString);
+        }
+        const out = queryString ? `${base}?${queryString}${hash}` : `${base}${hash}`;
+        if (debug) {
+            console.log('[Navigation.query][debug] out:', out);
+        }
+        return out;
+    }
+}
+export default new NavService();

package/dist/services/navigation/types.d.ts

@@ -0,0 +1,13 @@
+import type { getPathFromState, getStateFromPath, NavigationHelpers, NavigationProp, NavigationState, ParamListBase } from '@react-navigation/native';
+export type GetStateOpts = Parameters<typeof getStateFromPath>[1];
+export type GetPathOpts = Parameters<typeof getPathFromState>[1];
+export type NavLike = NavigationProp<ParamListBase> | NavigationHelpers<ParamListBase> | {
+    dispatch: (action: any) => void;
+    getState?: () => NavigationState;
+    getParent?: () => any;
+    popTo?: (name: string, params?: any) => void;
+};
+export type Leaf = {
+    name: string;
+    params?: Record<string, any>;
+};

package/dist/services/navigation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/navigation/zod-adapter.d.ts

@@ -0,0 +1,22 @@
+import type { NavigationValidator, RouteDef } from '../../config/navigation.types';
+export type SafeParseSchema<T = unknown> = {
+    safeParse: (input: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues?: any[];
+            message?: string;
+        };
+    };
+};
+export type NavSchemaRegistry = {
+    params?: SafeParseSchema;
+    query?: SafeParseSchema;
+};
+export type NavSchemas = Record<string, NavSchemaRegistry>;
+declare function createZodValidator(schemas: NavSchemas, opts?: {
+    keyOfRoute?: (r: RouteDef<any, any>) => string;
+}): NavigationValidator;
+export default createZodValidator;

package/dist/services/navigation/zod-adapter.js

@@ -0,0 +1,36 @@
+function issueMessage(err) {
+    const issues = err?.issues;
+    if (Array.isArray(issues) && issues.length) {
+        const first = issues[0];
+        const path = Array.isArray(first?.path) ? first.path.join('.') : '';
+        const msg = first?.message ?? 'Invalid';
+        return path ? `${path}: ${msg}` : msg;
+    }
+    return err?.message ?? 'Invalid';
+}
+function createZodValidator(schemas, opts) {
+    const keyOfRoute = opts?.keyOfRoute ?? (r => r.linking);
+    return {
+        validateBuild: (route, params) => {
+            const entry = schemas[keyOfRoute(route)];
+            const schema = entry?.params;
+            if (!schema)
+                return { ok: true };
+            const res = schema.safeParse(params);
+            if (res.success)
+                return { ok: true };
+            return { ok: false, message: `params invalid: ${issueMessage(res.error)}` };
+        },
+        validateQuery: (route, query) => {
+            const entry = schemas[keyOfRoute(route)];
+            const schema = entry?.query;
+            if (!schema)
+                return { ok: true };
+            const res = schema.safeParse(query);
+            if (res.success)
+                return { ok: true };
+            return { ok: false, message: `query invalid: ${issueMessage(res.error)}` };
+        },
+    };
+}
+export default createZodValidator;