@azure-net/kit 6.0.0-next.1 → 6.0.0-next.3

package/README.md

@@ -2,6 +2,106 @@
 
 #### [docs](https://svelte.kit.azure-net.ru)
 
+## Version 6 integration
+
+Configure `AzureNetPlugin()` from `@azure-net/kit/plugin` alongside SvelteKit in Vite,
+then export `{ register }` from `createApp(...)` in `src/program.ts`.
+Call `register()` synchronously during root layout initialization. `useClient` may
+be asynchronous: the navigation subscription is installed synchronously, and
+middleware supplied after an `await` applies only from that point onward. Handle
+the returned Promise if client initialization can fail. Client middleware itself
+must remain synchronous.
+
+The plugin provides virtual hooks only. It does not create or rewrite page/layout
+modules. Manual `hooks.server`, `hooks.client` and `hooks` files are forbidden.
+Initial Edges SSR state is hydrated once; later navigation is client-owned.
+
+`program.ts` is universal: a static server-only import does not become safe merely
+because it is used inside `useServer`. Use an explicit build-time browser guard
+with dynamic server imports when needed, and retain SvelteKit's build checks.
+
+### Application structure
+
+```text
+src/app/
+  Contexts/{Orders,Identity,SharedKernel}/
+    Domain/{Entities,Ports,Enums}
+    Infrastructure/Repositories
+    Application/UseCases
+  Presentation/{Admin,Public,Shared}/
+    Ui/
+    Scopes/
+    Shell/
+  Platform/
+    Foundation/{Datasource,Response,Schema,DI}
+    Bootstrap/{Routes,Localization}
+```
+
+Without workspaces, `Ui`, `Scopes` and `Shell` sit directly under `Presentation`.
+Central DI lives in `Platform/Foundation/DI/ApplicationProvider.ts`. Contexts may
+import `SharedKernel`, but not each other. Presentation scopes may compose any
+contexts. Workspaces may import `Shared`, but not each other.
+
+Boundary providers cache their proxy, registration and services per SSR request,
+not globally. Browser instances are cached until cleanup. Factories and `boot`
+are synchronous. `await cleanupProvider(name)` explicitly disposes instantiated
+services and resets the cache; request completion does not invoke it automatically.
+
+Install the CLI separately with `npm i -D @azure-net/cli`. Its commit-tools command
+configures Prettier without installing commit packages. `azure-net commit` commits
+staged changes; `azure-net push` checks, stages, commits and pushes. `--no-check`
+skips checks. Review `.gitignore` before staging.
+
+## Class Presenters And Async Helpers
+
+Import `createAsyncResource` and `createAsyncAction` directly from
+`@azure-net/kit/delivery`. `createAsyncHelpers()` has been removed. The error hook
+configured by `createApp().useAzureNetKitError` is still resolved per execution;
+there is no per-presenter parser or shared server error state. A custom error
+payload can be typed as the third generic: `createAsyncAction<Response, Request, CustomError>()`.
+
+```ts
+import { RegisterProvider, createAsyncResource } from '@azure-net/kit/delivery';
+import { ApplicationProvider } from '#platform/Foundation/DI';
+import type { OrdersUseCases } from '#contexts/Orders/Application/UseCases/OrdersUseCases';
+
+export class OrdersPresenter {
+	constructor(private readonly useCases: OrdersUseCases) {}
+
+	collection = () => createAsyncResource(() => this.useCases.collection());
+}
+
+export const useOrdersPresenter = RegisterProvider(() => {
+	const { Orders } = ApplicationProvider();
+	return new OrdersPresenter(Orders);
+}, 'scoped');
+```
+
+Call `useOrdersPresenter()` during component initialization, not at module scope.
+The registration itself is safe at module scope and does not resolve dependencies.
+Arrow fields remain callable after destructuring. `RegisterProvider` returns the
+actual class instance, without a proxy or automatic method binding.
+Classes using Svelte runes such as `$state` must be placed in a `.svelte.ts` module
+(or declared inside a Svelte component), not a regular `.ts` file.
+
+| Lifecycle                                  | Server                                    | Browser                       |
+| ------------------------------------------ | ----------------------------------------- | ----------------------------- |
+| `scoped` (default)                         | One instance per registration per request | New instance per call         |
+| `transient` (`trancient` is also accepted) | New instance per call                     | New instance per call         |
+| `singleton`                                | One instance per registration per request | One instance per registration |
+
+Server caching requires `AzureNetPlugin` request context and fails
+outside it. There is no process-wide server singleton. Request caches have weak
+keys and do not retain completed requests. Registrations do not require names,
+Svelte context, hydration, or state serialization. Factory callbacks must be
+synchronous; recursive construction is rejected.
+
+This API does not own effects, subscriptions, timers, or `dispose()`. Keep
+component-owned effects in component-lived instances; a cached browser singleton
+must not rely on effects owned by the first component that requested it. SSR
+isolation does not serialize state to the browser and cannot protect mutable
+module-level state captured by user factories.
+
 **@azure-net/kit** is a universal toolkit and library collection, developed as part of the **Azure-net** ecosystem. It is designed to speed up modern application development, reduce boilerplate code, and maintain a unified project architecture.
 
 ## ✨ What is it?
@@ -10,8 +110,8 @@
 
 ## 🚀 What's included?
 
-- **Built-in store** — flexible and SSR-friendly state management powered by [@azure-net/edges](https://github.com/Pixel1917/edge-s).
-- **Localization and translation** — ready-to-use i18n solution ([@azure-net/edges-translations](https://github.com/Pixel1917/edges-svelte-translations)) for multilingual applications.
+- **Reactive state classes** — request-isolated server instances and browser singletons via `RegisterProvider`.
+- **Localization and translation**: built-in rune-based i18n with request-scoped SSR instances. No edges or external translations dependency.
 - **Extensive utilities** — for working with text, objects, dates, and common tasks.
 - **Data validation** — handy rules and validators.
 - **Reusable base abstractions** — `Repositories`, `Services`, `Providers`, and `Datasources` for quick setup and reuse.
@@ -40,3 +140,79 @@ In this guide, you will find:
 ## 🚀 Get started
 
 Ready to dive in? Check out the [docs](https://svelte.kit.azure-net.ru) and start building your app faster and more reliably with **Azure-net**.
+
+## Initial state and `useBoot`
+
+`AzureNetPlugin()` owns a kit-local AsyncLocalStorage scope. It does not depend on
+edges, serialize stores, inject response scripts or create virtual route modules.
+There are no edges store/presenter exports or devtools exports in this version.
+`RequestContext.current()` exposes only `event` and `state`, is server-only, and
+throws outside an active request. Internal DI/error/lifecycle caches are private.
+
+Declare transferable state in `src/app.d.ts` (prefer optional fields for CSR):
+
+```ts
+import type { IUser } from '#contexts/Identity/Domain';
+declare global {
+	namespace App {
+		interface RequestContextState {
+			currentUser?: IUser | null;
+		}
+	}
+}
+export {};
+```
+
+```ts
+import { createApp } from '@azure-net/kit';
+import { RequestContext } from '@azure-net/kit/server-context';
+
+export const { register } = createApp((app) =>
+	app
+		.useServer(async ({ event, resolve, useMiddlewares }) => {
+			await useMiddlewares([ServerAuth]);
+			await TranslationManager().preloadTranslation();
+			return resolve(event);
+		})
+		.useBoot(({ state }) => {
+			useCurrentUser().setUser(state.currentUser ?? null);
+			TranslationManager().syncFromState(state);
+		})
+);
+```
+
+In the root layout call `register()` before resolving presenters or state classes.
+`useBoot` is synchronous and runs once per server request render and once per
+browser app initialization, before client lifecycle callbacks. Await all server
+state preparation before `resolve`. Do not mutate the transfer snapshot during
+rendering. Client navigations and repeated register calls do not rehydrate state.
+`useClientInit` runs earlier and must not depend on this snapshot. CSR without an
+SSR snapshot receives `{}`; initialize defaults and fetch missing data explicitly.
+Only publish safe DTOs, never tokens or the whole request/locals. Personalized HTML
+must not be publicly cached. Classes, functions and services are not serialized.
+
+Svelte currently requires async mode for `hydratable`:
+
+```ts
+sveltekit({ compilerOptions: { experimental: { async: true } } });
+```
+
+Keep the application's CSP correctly configured; Svelte manages the transfer
+script and serialization. No custom HTML parser is used by the kit.
+
+## DI naming
+
+`createBoundaryProvider` is replaced by `CreateServiceContainer` (no compatibility alias):
+
+```ts
+const ApplicationProvider = CreateDiContainer('ApplicationProvider', {
+	register: () => ({ Users: () => new UsersUseCases(repository) })
+});
+const { Users } = ApplicationProvider();
+```
+
+The accessor remains lazy, synchronous and request-scoped on SSR. `RegisterProvider`
+registers an individual class factory; `singleton` means one browser instance but
+one instance per request on the server, never a server process singleton.
+
+Built-in i18n: see [I18N.md](./I18N.md). preloadTranslation() fills request state automatically; syncFromState(state) restores it synchronously in useBoot. No separate translation package, writable/derived stores or edges adapter is required.

package/dist/delivery/index.d.ts

@@ -1,3 +1,4 @@
-export { createAsyncHelpers, type AsyncHelperRetry, type AsyncResourceSettings, type AsyncActionResponse } from './injectable-dependencies/index.js';
+export { createAsyncAction, createAsyncResource, type AsyncActionSettings, type AsyncHelperRetry, type AsyncResourceSettings, type AsyncActionResponse } from './injectable-dependencies/index.js';
+export { RegisterProvider, type ProviderLifecycle } from './presenter/RegisterProvider.js';
 export { createSchemaFactory, schema, type Schema, type RequestErrors, type ISchemaError, type ValidationResult, type ValidationRuleResult, type ValidationParams, type ValidationMessage, type ValidationErrorsMap } from './schema/index.js';
 export { createRules, validationMessagesRu, validationMessagesI18n, validationMessagesEn, type ValidationRuleParams, type BaseValidationMessages } from './schema/rules/index.js';

package/dist/delivery/index.js

@@ -1,3 +1,4 @@
-export { createAsyncHelpers } from './injectable-dependencies/index.js';
+export { createAsyncAction, createAsyncResource } from './injectable-dependencies/index.js';
+export { RegisterProvider } from './presenter/RegisterProvider.js';
 export { createSchemaFactory, schema } from './schema/index.js';
 export { createRules, validationMessagesRu, validationMessagesI18n, validationMessagesEn } from './schema/rules/index.js';

package/dist/delivery/injectable-dependencies/AsyncHelpers.d.ts

@@ -18,7 +18,5 @@ export interface AsyncActionSettings<Res = never, Req = never, ErrorResult = App
 export interface AsyncResourceSettings<Res = never, Req = never, ErrorResult = AppError<Error>> extends AsyncActionSettings<Res, Req, ErrorResult> {
     reject?: boolean;
 }
-export declare const createAsyncHelpers: <ErrorResult extends object>() => {
-    createAsyncAction: <Res = never, Req = never>(action: Action<Res>, args?: AsyncActionSettings<Res, Req, ErrorResult>) => Promise<AsyncActionResponse<Res, Req, ErrorResult>>;
-    createAsyncResource: <Res = never, Req_1 = never>(action: Action<Res>, args?: AsyncResourceSettings<Res, Req_1, ErrorResult>) => Promise<Res>;
-};
+export declare const createAsyncAction: <Res = never, Req = never, ErrorResult extends object = Record<never, never>>(action: Action<Res>, args?: AsyncActionSettings<Res, Req, ErrorResult>) => Promise<AsyncActionResponse<Res, Req, ErrorResult>>;
+export declare const createAsyncResource: <Res = never, Req = never, ErrorResult extends object = Record<never, never>>(action: Action<Res>, args?: AsyncResourceSettings<Res, Req, ErrorResult>) => Promise<Res>;

package/dist/delivery/injectable-dependencies/AsyncHelpers.js

@@ -1,115 +1,109 @@
 import { AsyncHelperError } from '../../shared/app-error/AppError.js';
 import { resolveAzureNetKitError } from '../../shared/app-error/ErrorRuntime.js';
-export const createAsyncHelpers = () => {
-    const normalizeError = (err) => (err instanceof Error ? err : new Error(String(err)));
-    const prepareErrors = async (error, retry) => {
-        let retryResult = undefined;
-        const retryFunc = async () => {
-            if (retry) {
-                return await retry()
-                    .then((res) => {
-                    retryResult = res;
-                    return undefined;
-                })
-                    .catch((err) => normalizeError(err));
-            }
-        };
-        const parsedError = await resolveAzureNetKitError(normalizeError(error), {
-            can: !!retry,
-            call: retry ? () => retryFunc() : undefined
-        });
-        return { error: parsedError, retryResult };
-    };
-    const beforeSendResolver = async (settings) => {
-        if (!settings?.beforeSend)
-            return undefined;
-        let abortReason;
-        let aborted = false;
-        await new Promise((resolve) => {
-            let settled = false;
-            const beforeSend = settings.beforeSend;
-            const guardTimer = setTimeout(() => {
-                settle(true);
-            }, 30000);
-            const settle = (isAbort, reason) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(guardTimer);
-                aborted = isAbort;
-                abortReason = reason;
-                resolve();
-            };
-            const next = () => settle(false);
-            const abort = (reason) => settle(true, reason);
-            try {
-                const maybePromise = beforeSend({ next, abort });
-                if (maybePromise && typeof maybePromise.then === 'function') {
-                    maybePromise.then(() => settle(false), (err) => settle(true, normalizeError(err)));
-                    return;
-                }
-                settle(false);
-            }
-            catch (err) {
-                settle(true, normalizeError(err));
-            }
-        });
-        if (!aborted)
-            return undefined;
-        const { error } = await prepareErrors(abortReason ?? new AsyncHelperError('Aborted in beforeSend'));
-        return {
-            success: false,
-            error,
-            response: undefined
-        };
+const normalizeError = (err) => (err instanceof Error ? err : new Error(String(err)));
+const prepareErrors = async (error, retry) => {
+    let retryResult = undefined;
+    const retryFunc = async () => {
+        if (retry) {
+            return await retry()
+                .then((res) => {
+                retryResult = res;
+                return undefined;
+            })
+                .catch((err) => normalizeError(err));
+        }
     };
-    const createAsyncAction = async (action, args) => {
-        const beforeSendResult = await beforeSendResolver(args);
-        if (beforeSendResult)
-            return beforeSendResult;
-        const executeAction = async () => {
-            const response = await Promise.resolve(action());
-            return { response, success: true };
-        };
-        const handleFailure = async (err, retry) => {
-            const { error, retryResult } = await prepareErrors(normalizeError(err), retry);
-            if (retryResult) {
-                return completeSuccess(retryResult);
-            }
-            const result = { error, response: args?.fallbackResponse, success: false };
-            try {
-                await args?.onError?.(result);
-            }
-            catch (onErrorException) {
-                throw await resolveAzureNetKitError(new AsyncHelperError('onError caught exception', { cause: normalizeError(onErrorException) }));
-            }
-            return result;
-        };
-        const completeSuccess = async (result) => {
-            try {
-                await args?.onSuccess?.(result);
-                return result;
-            }
-            catch (err) {
-                return handleFailure(err);
-            }
+    const parsedError = await resolveAzureNetKitError(normalizeError(error), {
+        can: !!retry,
+        call: retry ? () => retryFunc() : undefined
+    });
+    return { error: parsedError, retryResult };
+};
+const beforeSendResolver = async (settings) => {
+    if (!settings?.beforeSend)
+        return undefined;
+    let abortReason;
+    let aborted = false;
+    await new Promise((resolve) => {
+        let settled = false;
+        const beforeSend = settings.beforeSend;
+        const guardTimer = setTimeout(() => {
+            settle(true);
+        }, 30000);
+        const settle = (isAbort, reason) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(guardTimer);
+            aborted = isAbort;
+            abortReason = reason;
+            resolve();
         };
+        const next = () => settle(false);
+        const abort = (reason) => settle(true, reason);
         try {
-            return completeSuccess(await executeAction());
+            const maybePromise = beforeSend({ next, abort });
+            if (maybePromise && typeof maybePromise.then === 'function') {
+                maybePromise.then(() => settle(false), (err) => settle(true, normalizeError(err)));
+                return;
+            }
+            settle(false);
         }
         catch (err) {
-            return handleFailure(err, executeAction);
+            settle(true, normalizeError(err));
         }
+    });
+    if (!aborted)
+        return undefined;
+    const { error } = await prepareErrors(abortReason ?? new AsyncHelperError('Aborted in beforeSend'));
+    return {
+        success: false,
+        error,
+        response: undefined
+    };
+};
+export const createAsyncAction = async (action, args) => {
+    const beforeSendResult = await beforeSendResolver(args);
+    if (beforeSendResult)
+        return beforeSendResult;
+    const executeAction = async () => {
+        const response = await Promise.resolve(action());
+        return { response, success: true };
     };
-    const createAsyncResource = async (action, args) => {
-        const result = await createAsyncAction(action, args);
-        if (!result.success && args?.reject) {
-            throw result.error;
+    const handleFailure = async (err, retry) => {
+        const { error, retryResult } = await prepareErrors(normalizeError(err), retry);
+        if (retryResult) {
+            return completeSuccess(retryResult);
+        }
+        const result = { error, response: args?.fallbackResponse, success: false };
+        try {
+            await args?.onError?.(result);
+        }
+        catch (onErrorException) {
+            throw await resolveAzureNetKitError(new AsyncHelperError('onError caught exception', { cause: normalizeError(onErrorException) }));
         }
-        return result.response;
+        return result;
     };
-    return {
-        createAsyncAction,
-        createAsyncResource
+    const completeSuccess = async (result) => {
+        try {
+            await args?.onSuccess?.(result);
+            return result;
+        }
+        catch (err) {
+            return handleFailure(err);
+        }
     };
+    try {
+        return completeSuccess(await executeAction());
+    }
+    catch (err) {
+        return handleFailure(err, executeAction);
+    }
+};
+export const createAsyncResource = async (action, args) => {
+    const result = await createAsyncAction(action, args);
+    if (!result.success && args?.reject) {
+        throw result.error;
+    }
+    return result.response;
 };

package/dist/delivery/presenter/RegisterProvider.d.ts

@@ -0,0 +1,9 @@
+export type ProviderLifecycle = 'scoped' | 'transient' | 'singleton';
+/**
+ * Registration is safe at module scope; the factory is called only by the returned accessor.
+ * scoped: per request on the server, per call in the browser.
+ * singleton: per request on the server, per registration in the browser.
+ * transient: a new instance on every call.
+ * No hydration, component context, effects or disposal are managed by this function.
+ */
+export declare function RegisterProvider<T extends object>(factory: () => T extends PromiseLike<unknown> ? never : T, lifecycle?: ProviderLifecycle): () => T;

package/dist/delivery/presenter/RegisterProvider.js

@@ -0,0 +1,51 @@
+import { RequestContext } from '../../shared/request-context/Internal.js';
+import { BROWSER } from '../../external/tools/index.js';
+/**
+ * Registration is safe at module scope; the factory is called only by the returned accessor.
+ * scoped: per request on the server, per call in the browser.
+ * singleton: per request on the server, per registration in the browser.
+ * transient: a new instance on every call.
+ * No hydration, component context, effects or disposal are managed by this function.
+ */
+export function RegisterProvider(factory, lifecycle = 'scoped') {
+    if (!['scoped', 'transient', 'singleton'].includes(lifecycle)) {
+        throw new TypeError(`[RegisterProvider] Unknown lifecycle: ${lifecycle}`);
+    }
+    const requests = new WeakMap();
+    let clientInstance;
+    let constructing = false;
+    const create = () => {
+        if (constructing)
+            throw new Error('[RegisterProvider] Circular presenter dependency.');
+        constructing = true;
+        try {
+            const instance = factory();
+            if (!instance || (typeof instance !== 'object' && typeof instance !== 'function')) {
+                throw new TypeError('[RegisterProvider] Factory must return an instance.');
+            }
+            if ('then' in instance && typeof instance.then === 'function') {
+                // Consume a rejected async factory without allowing an unhandled rejection.
+                void Promise.resolve(instance).catch(() => undefined);
+                throw new TypeError('[RegisterProvider] Factory must be synchronous.');
+            }
+            return instance;
+        }
+        finally {
+            constructing = false;
+        }
+    };
+    return () => {
+        if (lifecycle === 'transient')
+            return create();
+        if (BROWSER)
+            return lifecycle === 'singleton' ? (clientInstance ??= create()) : create();
+        // Weak keys do not retain finished requests or their presenter graphs.
+        const context = RequestContext.current();
+        let instance = requests.get(context);
+        if (!instance) {
+            instance = create();
+            requests.set(context, instance);
+        }
+        return instance;
+    };
+}

package/dist/delivery.d.ts

@@ -1,2 +1 @@
-export * from './external/edges/Edges.js';
 export * from './delivery/index.js';

package/dist/delivery.js

@@ -1,2 +1 @@
-export * from './external/edges/Edges.js';
 export * from './delivery/index.js';

package/dist/i18n/Internal.d.ts

@@ -0,0 +1,13 @@
+export interface TranslationLifecycle {
+    preloadTranslation(): Promise<void>;
+    initializeClient(): Promise<void>;
+    syncFromState(state: App.RequestContextState): void;
+    transformHtml(html: string): string;
+}
+declare const translationManager: unique symbol;
+export type TranslationManagerFactory = (() => object) & {
+    readonly [translationManager]: true;
+};
+export declare const bindTranslationLifecycle: (manager: object, lifecycle: TranslationLifecycle) => void;
+export declare const getTranslationLifecycle: (manager: object) => TranslationLifecycle;
+export {};

package/dist/i18n/Internal.js

@@ -0,0 +1,10 @@
+const lifecycles = new WeakMap();
+export const bindTranslationLifecycle = (manager, lifecycle) => {
+    lifecycles.set(manager, lifecycle);
+};
+export const getTranslationLifecycle = (manager) => {
+    const lifecycle = lifecycles.get(manager);
+    if (!lifecycle)
+        throw new Error('[AzureNetKit:i18n] Expected a manager returned by createTranslations().');
+    return lifecycle;
+};

package/dist/i18n/Translations.svelte.d.ts

@@ -0,0 +1,20 @@
+import { type TranslationManagerFactory } from './Internal.js';
+import type { Path, TranslationCookieOptions, MessageLoader, TranslationVariables } from './Types.js';
+export declare const createTranslations: <const TMessages extends Record<string, MessageLoader>, const TInitLocale extends Extract<keyof TMessages, string>>(params: {
+    messages: TMessages;
+    initLang: TInitLocale;
+    cookieName?: string;
+    cookieOptions?: TranslationCookieOptions;
+    initLangFromAcceptLanguage?: boolean;
+    prefix?: string;
+}) => (() => {
+    switchLocale: (requestedLocale: Extract<keyof TMessages, string>) => Promise<void>;
+    applyHtmlLocaleAttr: (html: string) => string;
+    subscribeLocaleChangeEvent: (listener: (locale: Extract<keyof TMessages, string>) => void) => (() => void);
+    t: (translation?: string | {
+        key: string | Path<Awaited<ReturnType<TMessages[TInitLocale]>>, "", []>;
+        vars?: TranslationVariables;
+    } | Path<Awaited<ReturnType<TMessages[TInitLocale]>>, "", []>, vars?: TranslationVariables) => string;
+    readonly locale: Extract<keyof TMessages, string>;
+    locales: Readonly<Record<Extract<keyof TMessages, string>, Extract<keyof TMessages, string>>>;
+}) & TranslationManagerFactory;