feat: support un-scoping via scope(null | '')

Author: antfubot

packages/devframe/src/client/rpc.ts

@@ -120,8 +120,13 @@ export interface DevframeRpcClient {
    * shared-state key, and streaming channel with `my-plugin:`, and
    * exposes a typed top-level `settings` store. This is the preferred way
    * to consume the client from a single tool's UI code.
+   *
+   * Pass `null` or `''` to un-scope and get the base client.
    */
-  scope: <NS extends string>(namespace: NS) => DevframeScopedClientContext<NS, SettingsForNamespace<NS>>
+  scope: {
+    <NS extends string>(namespace: NS): DevframeScopedClientContext<NS, SettingsForNamespace<NS>>
+    (namespace?: null | ''): DevframeRpcClient
+  }
 }
 
 export interface DevframeRpcClientMode {
@@ -324,7 +329,9 @@ export async function getDevframeRpcClient(
   // Namespace-scoped views are memoized per namespace so repeated
   // `client.scope('my-plugin')` calls return a stable object.
   const scopedCache = new Map<string, DevframeScopedClientContext<string>>()
-  rpc.scope = ((namespace: string) => {
+  rpc.scope = ((namespace?: string | null) => {
+    if (!namespace)
+      return rpc
     let scoped = scopedCache.get(namespace)
     if (!scoped) {
       scoped = createScopedClientContext(rpc, namespace)

packages/devframe/src/client/scope.test.ts

@@ -45,6 +45,18 @@ describe('client.scope()', () => {
     expect(scoped.rpc.namespace).toBe('my-plugin')
   })
 
+  it('un-scopes and returns the base client when passed null or empty string', () => {
+    const { rpc } = createMockClient()
+    // To properly test this, we need the `scope` method added to `rpc`, similar
+    // to what `getDevframeRpcClient` does in `rpc.ts`.
+    rpc.scope = (ns?: string | null) => (ns ? createScopedClientContext(rpc, ns) : rpc) as any
+    const scoped = rpc.scope('my-plugin')
+    expect(rpc.scope('')).toBe(rpc)
+    expect(rpc.scope(null)).toBe(rpc)
+    expect(scoped.scope('')).toBe(rpc)
+    expect(scoped.scope(null)).toBe(rpc)
+  })
+
   it('qualifies bare call/callEvent/callOptional method names', () => {
     const { rpc } = createMockClient()
     const scoped = createScopedClientContext(rpc, 'my-plugin')

packages/devframe/src/client/scope.ts

@@ -85,6 +85,8 @@ export interface DevframeScopedClientContext<NS extends string = string, Setting
   rpc: DevframeScopedClientRpc<NS>
   /** Persisted settings for this namespace (`global` + `project`). */
   settings: DevframeSettings<Settings>
+  /** Derive another scope, or pass `null` / `''` to get the base client. */
+  scope: DevframeRpcClient['scope']
 }
 
 /**
@@ -126,5 +128,6 @@ export function createScopedClientContext<NS extends string = string>(
     base: rpc,
     rpc: scopedRpc,
     settings: createClientSettings(rpc, namespace),
+    scope: rpc.scope,
   }
 }

packages/devframe/src/node/__tests__/scope.test.ts

@@ -38,6 +38,15 @@ describe('ctx.scope()', () => {
     expect(ctx.scope('my-plugin')).not.toBe(ctx.scope('other'))
   })
 
+  it('un-scopes and returns the base context when passed null or empty string', async () => {
+    const { ctx } = await createCtx()
+    const scoped = ctx.scope('my-plugin')
+    expect(ctx.scope('')).toBe(ctx)
+    expect(ctx.scope(null)).toBe(ctx)
+    expect(scoped.scope('')).toBe(ctx)
+    expect(scoped.scope(null)).toBe(ctx)
+  })
+
   it('exposes the base context and read-only fields', async () => {
     const { ctx } = await createCtx()
     const scoped = ctx.scope('my-plugin')

packages/devframe/src/node/context.ts

@@ -61,7 +61,9 @@ export async function createHostContext(options: CreateHostContextOptions): Prom
   // Namespace-scoped views are memoized per namespace so repeated
   // `ctx.scope('my-plugin')` calls return a stable object.
   const scopedCache = new Map<string, DevframeScopedNodeContext<string>>()
-  context.scope = ((namespace: string) => {
+  context.scope = ((namespace?: string | null) => {
+    if (!namespace)
+      return context
     let scoped = scopedCache.get(namespace)
     if (!scoped) {
       scoped = createScopedNodeContext(context, namespace)

packages/devframe/src/node/scope.ts

@@ -56,5 +56,6 @@ export function createScopedNodeContext<NS extends string = string>(
     views: context.views,
     diagnostics: context.diagnostics,
     agent: context.agent,
+    scope: context.scope,
   }
 }

packages/devframe/src/types/context.ts

@@ -58,8 +58,13 @@ export interface DevframeNodeContext {
    * key, and streaming channel with `my-plugin:`, and exposes a typed
    * top-level `settings` store. This is the preferred way to consume the
    * context from a single tool's setup code.
+   *
+   * Pass `null` or `''` to un-scope and get the base context.
    */
-  scope: <NS extends string>(namespace: NS) => DevframeScopedNodeContext<NS, SettingsForNamespace<NS>>
+  scope: {
+    <NS extends string>(namespace: NS): DevframeScopedNodeContext<NS, SettingsForNamespace<NS>>
+    (namespace?: null | ''): DevframeNodeContext
+  }
 }
 
 export interface ConnectionMeta {

packages/devframe/src/types/scope.ts

@@ -208,4 +208,6 @@ export interface DevframeScopedNodeContext<NS extends string = string, Settings
   views: DevframeViewHost
   diagnostics: DevframeDiagnosticsHost
   agent: DevframeAgentHost
+  /** Derive another scope, or pass `null` / `''` to get the base context. */
+  scope: DevframeNodeContext['scope']
 }

tests/__snapshots__/tsnapi/devframe/client.snapshot.d.ts

@@ -16,7 +16,10 @@ export interface DevframeRpcClient {
   sharedState: RpcSharedStateHost;
   streaming: RpcStreamingClientHost;
   cacheManager: RpcCacheManager;
-  scope: <NS extends string>(_: NS) => DevframeScopedClientContext<NS, SettingsForNamespace<NS>>;
+  scope: {
+    <NS extends string>(_: NS): DevframeScopedClientContext<NS, SettingsForNamespace<NS>>;
+    (_?: null | ''): DevframeRpcClient;
+  };
 }
 export interface DevframeRpcClientMode {
   readonly isTrusted: boolean;
@@ -43,6 +46,7 @@ export interface DevframeScopedClientContext<NS extends string = string, Setting
   readonly base: DevframeRpcClient;
   rpc: DevframeScopedClientRpc<NS>;
   settings: DevframeSettings<Settings>;
+  scope: DevframeRpcClient['scope'];
 }
 export interface DevframeScopedClientRpc<NS extends string = string> {
   readonly namespace: NS;