@burojs/context 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,197 @@
+type PermissionStatus = 'loading' | 'ready' | 'error';
+/**
+ * Permission resolver returned by user's permissions slice.
+ * Default behavior contract:
+ *   loading: visible=true, enabled=false (UI shows controls in disabled state)
+ *   error: visible=false, enabled=false (fail-closed)
+ *   ready: normal evaluation
+ */
+interface PermissionMap {
+    status: PermissionStatus;
+    can: (action: string, resource: string, record?: unknown) => boolean;
+    reason: (action: string, resource: string, record?: unknown) => string | undefined;
+}
+
+type SliceKind = 'static' | 'fromAuth' | 'picker' | 'async';
+/**
+ * Common shape for all slice definitions.
+ * Specific kinds extend this with kind-specific fields (defined in slices/*.ts).
+ */
+interface SliceDefinition<TName extends string = string, TValue = unknown> {
+    name: TName;
+    kind: SliceKind;
+    deps: string[];
+    /** Phantom — for type inference of slice value types. */
+    __valueType?: TValue;
+}
+
+interface Store<TState extends Record<string, unknown>> {
+    snapshot: () => TState;
+    setSlice: <K extends keyof TState>(key: K, value: TState[K]) => void;
+    subscribe: (fn: () => void, selector?: (state: TState) => unknown) => () => void;
+}
+
+interface Atom<T> {
+    get: () => T;
+    set: (value: T) => void;
+    subscribe: (fn: () => void) => () => void;
+}
+declare function createAtom<T>(initial: T): Atom<T>;
+
+declare function createStore<TState extends Record<string, unknown>>(initial: TState): Store<TState>;
+
+/**
+ * Proxy-based read tracking. The selector function reads from a Proxy
+ * wrapping the target; every property access is recorded with dotted-path keys.
+ *
+ * Used by store.subscribe to know exactly which slice keys a subscriber depends on,
+ * enabling point-wise re-invocation only when relevant slices change.
+ */
+interface TrackedReadResult<T> {
+    result: T;
+    deps: Set<string>;
+}
+declare function trackReads<TCtx, TResult>(ctx: TCtx, selector: (c: TCtx) => TResult): TrackedReadResult<TResult>;
+
+interface DagNode {
+    name: string;
+    deps: string[];
+}
+/**
+ * Kahn-style topological sort with cycle detection.
+ * Throws on cycles (with path) and on missing dependencies.
+ */
+declare function topoSort<N extends DagNode>(nodes: N[]): N[];
+
+interface StaticSliceDefinition<TName extends string, TValue> extends SliceDefinition<TName, TValue> {
+    kind: 'static';
+    value: () => TValue;
+}
+interface StaticSliceConfig<TValue> {
+    value: TValue | (() => TValue);
+}
+declare function defineStaticSlice<TName extends string, TValue>(name: TName, config: StaticSliceConfig<TValue>): StaticSliceDefinition<TName, TValue>;
+
+type AuthInvalidationEvent = 'login' | 'logout' | 'refresh';
+interface FromAuthSliceDefinition<TName extends string, TValue> extends SliceDefinition<TName, TValue> {
+    kind: 'fromAuth';
+    extract: (rawAuthUser: unknown) => TValue;
+    invalidateOn: AuthInvalidationEvent[];
+}
+interface FromAuthSliceConfig<TValue> {
+    extract: (rawAuthUser: never) => TValue;
+    invalidateOn?: AuthInvalidationEvent[];
+}
+declare function defineFromAuthSlice<TName extends string, TValue>(name: TName, config: FromAuthSliceConfig<TValue>): FromAuthSliceDefinition<TName, TValue>;
+
+type PickerPersistMode = 'localStorage' | 'sessionStorage' | 'url';
+/**
+ * Picker target — minimal contract. Real ResourceDef from @burojs/core
+ * has full shape; here we accept anything thunk-returning a name.
+ *
+ * SCOPE-ISOLATION CONTRACT:
+ *   The picker-slice NEVER reads `target.scope` or `target.requireScope`.
+ *
+ *   ⚠️ This comment used to also list `picker.label` / `picker.searchFields`
+ *   / `picker.listColumns` / `picker.filters` as properties the slice reads.
+ *   It never read them: `definePickerSlice` is a pure descriptor factory and
+ *   touches none of them. The `ResourceConfig.picker` block those names came
+ *   from was deleted in the core-flexibility program (sub-project D) as dead
+ *   API — it had no reader anywhere in the repo, and only survived a type
+ *   error because `define-resource.ts` copied it through with an `as any`.
+ *   Resolver emits a dev-warning if target has those set.
+ */
+interface PickerSliceDefinition<TName extends string, TValue> extends SliceDefinition<TName, TValue> {
+    kind: 'picker';
+    resource: () => unknown;
+    filter?: (ctx: never) => Record<string, unknown>;
+    resetWhen?: string[];
+    persist?: PickerPersistMode;
+    required: boolean;
+}
+interface PickerSliceConfig {
+    resource: () => unknown;
+    dependsOn?: string[];
+    filter?: (ctx: never) => Record<string, unknown>;
+    resetWhen?: string[];
+    persist?: PickerPersistMode;
+    required?: boolean;
+}
+declare function definePickerSlice<TName extends string, TValue = unknown>(name: TName, config: PickerSliceConfig): PickerSliceDefinition<TName, TValue>;
+
+interface AsyncSliceDefinition<TName extends string, TValue> extends SliceDefinition<TName, TValue> {
+    kind: 'async';
+    fetch: (ctx: never) => Promise<TValue>;
+    cacheKey?: (ctx: never) => string;
+    staleTime: number;
+}
+interface AsyncSliceConfig<TValue> {
+    dependsOn?: string[];
+    fetch: (ctx: never) => Promise<TValue>;
+    cacheKey?: (ctx: never) => string;
+    /** ms; 0 = always refetch on invalidation */
+    staleTime?: number;
+}
+declare function defineAsyncSlice<TName extends string, TValue>(name: TName, config: AsyncSliceConfig<TValue>): AsyncSliceDefinition<TName, TValue>;
+
+interface SliceBuilder {
+    static: <TValue>(config: StaticSliceConfig<TValue>) => StaticSliceDefinition<string, TValue>;
+    fromAuth: <TValue>(config: FromAuthSliceConfig<TValue>) => FromAuthSliceDefinition<string, TValue>;
+    picker: <TValue = unknown>(config: PickerSliceConfig) => PickerSliceDefinition<string, TValue>;
+    async: <TValue>(config: AsyncSliceConfig<TValue>) => AsyncSliceDefinition<string, TValue>;
+}
+declare function defineContextSlices<T extends Record<string, SliceDefinition>>(factory: (s: SliceBuilder) => T): T;
+
+interface Resolver<TSlices extends Record<string, SliceDefinition>> {
+    boot: () => Promise<void>;
+    snapshot: () => {
+        [K in keyof TSlices]: unknown;
+    };
+    setSlice: <K extends keyof TSlices>(key: K, value: unknown) => void;
+    subscribe: (fn: () => void, selector?: (s: never) => unknown) => () => void;
+    feedAuth: (rawAuthUser: unknown) => void;
+    flushAsync: () => Promise<void>;
+}
+declare function createResolver<TSlices extends Record<string, SliceDefinition>>(slices: TSlices): Resolver<TSlices>;
+
+type Scope = Record<string, unknown> | null;
+interface ScopeChainEntry {
+    name: string;
+    scope: (ctx: never) => Scope;
+}
+/**
+ * Shallow merge two scope objects. Patch wins on conflict.
+ * null on either side is treated as "no contribution".
+ */
+declare function mergeScope(base: Scope, patch: Scope): Scope;
+/**
+ * Cascade scope down a parent → child chain.
+ * Each entry's scope() is invoked with ctx; results are merged left-to-right.
+ * Later entries override earlier ones (child wins).
+ */
+declare function cascadeScope(chain: ScopeChainEntry[], ctx: never): Scope;
+interface RequireScopeOk {
+    ok: true;
+}
+interface RequireScopeFail {
+    ok: false;
+    missing: string[];
+}
+type RequireScopeResult = RequireScopeOk | RequireScopeFail;
+/**
+ * Verify all required keys are present (and not undefined) in scope.
+ */
+declare function checkRequireScope(scope: Scope, required: string[]): RequireScopeResult;
+
+declare function createPendingPermissions(): PermissionMap;
+declare function createErrorPermissions(error: unknown): PermissionMap;
+interface ReadyPermissionsConfig {
+    can: (action: string, resource: string, record?: unknown) => boolean;
+    reason?: (action: string, resource: string, record?: unknown) => string | undefined;
+}
+declare function createReadyPermissions(config: ReadyPermissionsConfig): PermissionMap;
+
+declare const PACKAGE_NAME: "@burojs/context";
+declare const PACKAGE_VERSION: "0.0.0";
+
+export { type AsyncSliceConfig, type AsyncSliceDefinition, type Atom, type AuthInvalidationEvent, type DagNode, type FromAuthSliceConfig, type FromAuthSliceDefinition, PACKAGE_NAME, PACKAGE_VERSION, type PermissionMap, type PermissionStatus, type PickerPersistMode, type PickerSliceConfig, type PickerSliceDefinition, type ReadyPermissionsConfig, type RequireScopeFail, type RequireScopeOk, type RequireScopeResult, type Resolver, type Scope, type ScopeChainEntry, type SliceBuilder, type SliceDefinition, type SliceKind, type StaticSliceConfig, type StaticSliceDefinition, type Store, type TrackedReadResult, cascadeScope, checkRequireScope, createAtom, createErrorPermissions, createPendingPermissions, createReadyPermissions, createResolver, createStore, defineAsyncSlice, defineContextSlices, defineFromAuthSlice, definePickerSlice, defineStaticSlice, mergeScope, topoSort, trackReads };

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+type PermissionStatus = 'loading' | 'ready' | 'error';
+/**
+ * Permission resolver returned by user's permissions slice.
+ * Default behavior contract:
+ *   loading: visible=true, enabled=false (UI shows controls in disabled state)
+ *   error: visible=false, enabled=false (fail-closed)
+ *   ready: normal evaluation
+ */
+interface PermissionMap {
+    status: PermissionStatus;
+    can: (action: string, resource: string, record?: unknown) => boolean;
+    reason: (action: string, resource: string, record?: unknown) => string | undefined;
+}
+
+type SliceKind = 'static' | 'fromAuth' | 'picker' | 'async';
+/**
+ * Common shape for all slice definitions.
+ * Specific kinds extend this with kind-specific fields (defined in slices/*.ts).
+ */
+interface SliceDefinition<TName extends string = string, TValue = unknown> {
+    name: TName;
+    kind: SliceKind;
+    deps: string[];
+    /** Phantom — for type inference of slice value types. */
+    __valueType?: TValue;
+}
+
+interface Store<TState extends Record<string, unknown>> {
+    snapshot: () => TState;
+    setSlice: <K extends keyof TState>(key: K, value: TState[K]) => void;
+    subscribe: (fn: () => void, selector?: (state: TState) => unknown) => () => void;
+}
+
+interface Atom<T> {
+    get: () => T;
+    set: (value: T) => void;
+    subscribe: (fn: () => void) => () => void;
+}
+declare function createAtom<T>(initial: T): Atom<T>;
+
+declare function createStore<TState extends Record<string, unknown>>(initial: TState): Store<TState>;
+
+/**
+ * Proxy-based read tracking. The selector function reads from a Proxy
+ * wrapping the target; every property access is recorded with dotted-path keys.
+ *
+ * Used by store.subscribe to know exactly which slice keys a subscriber depends on,
+ * enabling point-wise re-invocation only when relevant slices change.
+ */
+interface TrackedReadResult<T> {
+    result: T;
+    deps: Set<string>;
+}
+declare function trackReads<TCtx, TResult>(ctx: TCtx, selector: (c: TCtx) => TResult): TrackedReadResult<TResult>;
+
+interface DagNode {
+    name: string;
+    deps: string[];
+}
+/**
+ * Kahn-style topological sort with cycle detection.
+ * Throws on cycles (with path) and on missing dependencies.
+ */
+declare function topoSort<N extends DagNode>(nodes: N[]): N[];
+
+interface StaticSliceDefinition<TName extends string, TValue> extends SliceDefinition<TName, TValue> {
+    kind: 'static';
+    value: () => TValue;
+}
+interface StaticSliceConfig<TValue> {
+    value: TValue | (() => TValue);
+}
+declare function defineStaticSlice<TName extends string, TValue>(name: TName, config: StaticSliceConfig<TValue>): StaticSliceDefinition<TName, TValue>;
+
+type AuthInvalidationEvent = 'login' | 'logout' | 'refresh';
+interface FromAuthSliceDefinition<TName extends string, TValue> extends SliceDefinition<TName, TValue> {
+    kind: 'fromAuth';
+    extract: (rawAuthUser: unknown) => TValue;
+    invalidateOn: AuthInvalidationEvent[];
+}
+interface FromAuthSliceConfig<TValue> {
+    extract: (rawAuthUser: never) => TValue;
+    invalidateOn?: AuthInvalidationEvent[];
+}
+declare function defineFromAuthSlice<TName extends string, TValue>(name: TName, config: FromAuthSliceConfig<TValue>): FromAuthSliceDefinition<TName, TValue>;
+
+type PickerPersistMode = 'localStorage' | 'sessionStorage' | 'url';
+/**
+ * Picker target — minimal contract. Real ResourceDef from @burojs/core
+ * has full shape; here we accept anything thunk-returning a name.
+ *
+ * SCOPE-ISOLATION CONTRACT:
+ *   The picker-slice NEVER reads `target.scope` or `target.requireScope`.
+ *
+ *   ⚠️ This comment used to also list `picker.label` / `picker.searchFields`
+ *   / `picker.listColumns` / `picker.filters` as properties the slice reads.
+ *   It never read them: `definePickerSlice` is a pure descriptor factory and
+ *   touches none of them. The `ResourceConfig.picker` block those names came
+ *   from was deleted in the core-flexibility program (sub-project D) as dead
+ *   API — it had no reader anywhere in the repo, and only survived a type
+ *   error because `define-resource.ts` copied it through with an `as any`.
+ *   Resolver emits a dev-warning if target has those set.
+ */
+interface PickerSliceDefinition<TName extends string, TValue> extends SliceDefinition<TName, TValue> {
+    kind: 'picker';
+    resource: () => unknown;
+    filter?: (ctx: never) => Record<string, unknown>;
+    resetWhen?: string[];
+    persist?: PickerPersistMode;
+    required: boolean;
+}
+interface PickerSliceConfig {
+    resource: () => unknown;
+    dependsOn?: string[];
+    filter?: (ctx: never) => Record<string, unknown>;
+    resetWhen?: string[];
+    persist?: PickerPersistMode;
+    required?: boolean;
+}
+declare function definePickerSlice<TName extends string, TValue = unknown>(name: TName, config: PickerSliceConfig): PickerSliceDefinition<TName, TValue>;
+
+interface AsyncSliceDefinition<TName extends string, TValue> extends SliceDefinition<TName, TValue> {
+    kind: 'async';
+    fetch: (ctx: never) => Promise<TValue>;
+    cacheKey?: (ctx: never) => string;
+    staleTime: number;
+}
+interface AsyncSliceConfig<TValue> {
+    dependsOn?: string[];
+    fetch: (ctx: never) => Promise<TValue>;
+    cacheKey?: (ctx: never) => string;
+    /** ms; 0 = always refetch on invalidation */
+    staleTime?: number;
+}
+declare function defineAsyncSlice<TName extends string, TValue>(name: TName, config: AsyncSliceConfig<TValue>): AsyncSliceDefinition<TName, TValue>;
+
+interface SliceBuilder {
+    static: <TValue>(config: StaticSliceConfig<TValue>) => StaticSliceDefinition<string, TValue>;
+    fromAuth: <TValue>(config: FromAuthSliceConfig<TValue>) => FromAuthSliceDefinition<string, TValue>;
+    picker: <TValue = unknown>(config: PickerSliceConfig) => PickerSliceDefinition<string, TValue>;
+    async: <TValue>(config: AsyncSliceConfig<TValue>) => AsyncSliceDefinition<string, TValue>;
+}
+declare function defineContextSlices<T extends Record<string, SliceDefinition>>(factory: (s: SliceBuilder) => T): T;
+
+interface Resolver<TSlices extends Record<string, SliceDefinition>> {
+    boot: () => Promise<void>;
+    snapshot: () => {
+        [K in keyof TSlices]: unknown;
+    };
+    setSlice: <K extends keyof TSlices>(key: K, value: unknown) => void;
+    subscribe: (fn: () => void, selector?: (s: never) => unknown) => () => void;
+    feedAuth: (rawAuthUser: unknown) => void;
+    flushAsync: () => Promise<void>;
+}
+declare function createResolver<TSlices extends Record<string, SliceDefinition>>(slices: TSlices): Resolver<TSlices>;
+
+type Scope = Record<string, unknown> | null;
+interface ScopeChainEntry {
+    name: string;
+    scope: (ctx: never) => Scope;
+}
+/**
+ * Shallow merge two scope objects. Patch wins on conflict.
+ * null on either side is treated as "no contribution".
+ */
+declare function mergeScope(base: Scope, patch: Scope): Scope;
+/**
+ * Cascade scope down a parent → child chain.
+ * Each entry's scope() is invoked with ctx; results are merged left-to-right.
+ * Later entries override earlier ones (child wins).
+ */
+declare function cascadeScope(chain: ScopeChainEntry[], ctx: never): Scope;
+interface RequireScopeOk {
+    ok: true;
+}
+interface RequireScopeFail {
+    ok: false;
+    missing: string[];
+}
+type RequireScopeResult = RequireScopeOk | RequireScopeFail;
+/**
+ * Verify all required keys are present (and not undefined) in scope.
+ */
+declare function checkRequireScope(scope: Scope, required: string[]): RequireScopeResult;
+
+declare function createPendingPermissions(): PermissionMap;
+declare function createErrorPermissions(error: unknown): PermissionMap;
+interface ReadyPermissionsConfig {
+    can: (action: string, resource: string, record?: unknown) => boolean;
+    reason?: (action: string, resource: string, record?: unknown) => string | undefined;
+}
+declare function createReadyPermissions(config: ReadyPermissionsConfig): PermissionMap;
+
+declare const PACKAGE_NAME: "@burojs/context";
+declare const PACKAGE_VERSION: "0.0.0";
+
+export { type AsyncSliceConfig, type AsyncSliceDefinition, type Atom, type AuthInvalidationEvent, type DagNode, type FromAuthSliceConfig, type FromAuthSliceDefinition, PACKAGE_NAME, PACKAGE_VERSION, type PermissionMap, type PermissionStatus, type PickerPersistMode, type PickerSliceConfig, type PickerSliceDefinition, type ReadyPermissionsConfig, type RequireScopeFail, type RequireScopeOk, type RequireScopeResult, type Resolver, type Scope, type ScopeChainEntry, type SliceBuilder, type SliceDefinition, type SliceKind, type StaticSliceConfig, type StaticSliceDefinition, type Store, type TrackedReadResult, cascadeScope, checkRequireScope, createAtom, createErrorPermissions, createPendingPermissions, createReadyPermissions, createResolver, createStore, defineAsyncSlice, defineContextSlices, defineFromAuthSlice, definePickerSlice, defineStaticSlice, mergeScope, topoSort, trackReads };