feat: add 'debugPrivate' flag to atom

src/vanilla/atom.ts

@@ -34,8 +34,13 @@ type OnMount<Args extends unknown[], Result> = <
 
 export interface Atom<Value> {
   toString: () => string
-  debugLabel?: string
   read: Read<Value>
+  debugLabel?: string
+  /**
+   * To ONLY be used by Jotai libraries to mark atoms as private. Subject to change.
+   * @private
+   */
+  debugPrivate?: boolean
 }
 
 export interface WritableAtom<Value, Args extends unknown[], Result>

src/vanilla/utils/atomWithDefault.ts

@@ -37,6 +37,11 @@ export function atomWithDefault<Value>(
 ) {
   const EMPTY = Symbol()
   const overwrittenAtom = atom<Value | typeof EMPTY>(EMPTY)
+
+  if (import.meta.env?.MODE !== 'production') {
+    overwrittenAtom.debugPrivate = true
+  }
+
   const anAtom: WritableAtom<
     Value,
     [SetStateAction<Awaited<Value>> | typeof RESET],

src/vanilla/utils/atomWithObservable.ts

@@ -135,6 +135,11 @@ export function atomWithObservable<Data>(
     start()
 
     const resultAtom = atom(lastResult || initialResult)
+
+    if (import.meta.env?.MODE !== 'production') {
+      resultAtom.debugPrivate = true
+    }
+
     resultAtom.onMount = (update) => {
       setResult = update
       if (lastResult) {
@@ -156,6 +161,10 @@ export function atomWithObservable<Data>(
     return [resultAtom, observable, makePending, start, isNotMounted] as const
   })
 
+  if (import.meta.env?.MODE !== 'production') {
+    observableResultAtom.debugPrivate = true
+  }
+
   const observableAtom = atom(
     (get) => {
       const [resultAtom] = get(observableResultAtom)

src/vanilla/utils/atomWithStorage.ts

@@ -108,6 +108,10 @@ export function atomWithStorage<Value>(
 ): WritableAtom<Value, [SetStateActionWithReset<Value>], void> {
   const baseAtom = atom(initialValue)
 
+  if (import.meta.env?.MODE !== 'production') {
+    baseAtom.debugPrivate = true
+  }
+
   baseAtom.onMount = (setAtom) => {
     const value = storage.getItem(key)
     if (value instanceof Promise) {

src/vanilla/utils/loadable.ts

@@ -16,6 +16,11 @@ export function loadable<Value>(anAtom: Atom<Value>): Atom<Loadable<Value>> {
   return memo1(() => {
     const loadableCache = new WeakMap<Promise<void>, Loadable<Value>>()
     const refreshAtom = atom(0)
+
+    if (import.meta.env?.MODE !== 'production') {
+      refreshAtom.debugPrivate = true
+    }
+
     const derivedAtom = atom(
       (get, { setSelf }) => {
         get(refreshAtom)
@@ -44,6 +49,11 @@ export function loadable<Value>(anAtom: Atom<Value>): Atom<Loadable<Value>> {
         set(refreshAtom, (c) => c + 1)
       }
     )
+
+    if (import.meta.env?.MODE !== 'production') {
+      derivedAtom.debugPrivate = true
+    }
+
     return atom((get) => get(derivedAtom))
   }, anAtom)
 }

src/vanilla/utils/splitAtom.ts

@@ -140,6 +140,11 @@ export function splitAtom<Item, Key>(
         const mapping = getMapping(arr, prev?.arr)
         return mapping
       })
+
+      if (import.meta.env?.MODE !== 'production') {
+        mappingAtom.debugPrivate = true
+      }
+
       // HACK to read mapping atom before initialization
       mappingAtom.init = undefined
       const splittedAtom = isWritable(arrAtom)

src/vanilla/utils/unwrap.ts

@@ -33,6 +33,11 @@ export function unwrap<Value, PendingValue>(
       const promiseErrorCache = new WeakMap<Promise<Value>, unknown>()
       const promiseResultCache = new WeakMap<Promise<Value>, Awaited<Value>>()
       const refreshAtom = atom(0)
+
+      if (import.meta.env?.MODE !== 'production') {
+        refreshAtom.debugPrivate = true
+      }
+
       const promiseAndValueAtom: WritableAtom<PromiseAndValue, [], void> & {
         init?: undefined
       } = atom(
@@ -70,6 +75,11 @@ export function unwrap<Value, PendingValue>(
       )
       // HACK to read PromiseAndValue atom before initialization
       promiseAndValueAtom.init = undefined
+
+      if (import.meta.env?.MODE !== 'production') {
+        promiseAndValueAtom.debugPrivate = true
+      }
+
       return atom((get) => {
         const state = get(promiseAndValueAtom)
         if ('v' in state) {

tests/vanilla/basic.test.tsx

@@ -50,3 +50,18 @@ it('creates atoms', () => {
     }
   `)
 })
+
+it('should let users mark atoms as private', () => {
+  const internalAtom = atom(0)
+  internalAtom.debugPrivate = true
+
+  expect(internalAtom).toMatchInlineSnapshot(`
+    {
+      "debugPrivate": true,
+      "init": 0,
+      "read": [Function],
+      "toString": [Function],
+      "write": [Function],
+    }
+  `)
+})