@rific/splash-gate 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @rific/splash-gate
+
+Name every async condition your Expo app's first screen actually depends on (a loaded theme, a loaded icon font, a hydrated saved preference, an auth check) and hold the splash screen up until all of them report ready. One shared, tested utility instead of a fresh ad hoc module-scope gate copy-pasted into every project.
+
+## Why
+
+`SplashScreen.preventAutoHideAsync()` only holds the splash up. It's on you to call `hideAsync()` at the right moment. Call it too early (e.g. the instant your theme loads) and anything else your first screen depends on but forgot to wait for, an icon font, a hydrated preference, pops in visibly a moment after the splash lifts. `createSplashGate` makes every condition explicit up front, so nothing can be forgotten silently.
+
+## Installation
+
+```sh
+npm install @rific/splash-gate
+```
+
+## Usage
+
+```ts
+// splashGate.ts, created once, at module scope, listing every condition this app's first
+// screen actually depends on
+import { createSplashGate } from '@rific/splash-gate'
+
+export const { markReady, useReady, pendingGates } = createSplashGate(['theme', 'fonts', 'keyboardLayout'])
+```
+
+```tsx
+// Theme.tsx
+import * as SplashScreen from 'expo-splash-screen'
+import { useFonts } from 'expo-font'
+import { markReady, useReady } from './splashGate'
+
+SplashScreen.preventAutoHideAsync()
+
+export const Theme = ({ children }) => {
+  const [fontsLoaded] = useFonts({ ... })
+  useReady('fonts', fontsLoaded)
+
+  const onThemeReady = () => markReady('theme') // a one-shot callback, not a boolean, call directly
+
+  return <Provider onReady={onThemeReady}>{children}</Provider>
+}
+```
+
+```ts
+// KeyboardLayoutProvider.tsx
+import { useReady } from './splashGate'
+
+const [loaded, setLoaded] = useState(false)
+useEffect(() => {
+  void AsyncStorage.getItem(STORAGE_KEY).then((stored) => {
+    if (stored) setLayoutState(stored)
+    setLoaded(true) // mark loaded whether or not a saved value was actually found
+  })
+}, [])
+useReady('keyboardLayout', loaded)
+```
+
+The splash screen hides exactly once, the moment `theme`, `fonts`, and `keyboardLayout` have all reported ready, in whatever order they actually resolve.
+
+## API
+
+### `createSplashGate(gates)`
+
+Takes an array of gate names (typically `as const` for literal-type safety) and returns:
+
+- `markReady(gate)`: marks one gate ready. Safe to call more than once for the same gate, and safe in any order. Hides the splash screen exactly once, once every gate is ready. For a gate that only resolves via a one-shot callback (a library's own `onReady` prop, a promise `.then`), call this directly there.
+- `useReady(gate, ready)`: for a gate whose readiness is already a plain boolean (state from a hook like `useFonts`, or your own derived condition), marks it ready once `ready` becomes `true`. Bound to this gate instance, so there's nothing to pass but the two things that actually vary at each call site.
+- `pendingGates()`: the gate names still outstanding, for a debug log during development.
+
+Call this once, at module scope, not inside a component body, or you'll get a fresh gate (and a fresh splash-hide race) on every render.

package/dist/index.d.mts

@@ -0,0 +1,8 @@
+type SplashGate<T extends string> = {
+    markReady: (gate: T) => void;
+    useReady: (gate: T, ready: boolean) => void;
+    pendingGates: () => T[];
+};
+declare function createSplashGate<T extends string>(gates: readonly T[]): SplashGate<T>;
+
+export { type SplashGate, createSplashGate };

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+type SplashGate<T extends string> = {
+    markReady: (gate: T) => void;
+    useReady: (gate: T, ready: boolean) => void;
+    pendingGates: () => T[];
+};
+declare function createSplashGate<T extends string>(gates: readonly T[]): SplashGate<T>;
+
+export { type SplashGate, createSplashGate };

package/dist/index.js

@@ -0,0 +1,64 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createSplashGate: () => createSplashGate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/splashGate.ts
+var SplashScreen = __toESM(require("expo-splash-screen"));
+var import_react = require("react");
+function createSplashGate(gates) {
+  const pending = new Set(gates);
+  let hidden = false;
+  const tryHide = () => {
+    if (hidden || pending.size > 0) return;
+    hidden = true;
+    void SplashScreen.hideAsync();
+  };
+  const markReady = (gate) => {
+    pending.delete(gate);
+    tryHide();
+  };
+  const useReady = (gate, ready) => {
+    (0, import_react.useEffect)(() => {
+      if (ready) markReady(gate);
+    }, [ready, gate]);
+  };
+  const pendingGates = () => Array.from(pending);
+  tryHide();
+  return { markReady, useReady, pendingGates };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSplashGate
+});

package/dist/index.mjs

@@ -0,0 +1,27 @@
+// src/splashGate.ts
+import * as SplashScreen from "expo-splash-screen";
+import { useEffect } from "react";
+function createSplashGate(gates) {
+  const pending = new Set(gates);
+  let hidden = false;
+  const tryHide = () => {
+    if (hidden || pending.size > 0) return;
+    hidden = true;
+    void SplashScreen.hideAsync();
+  };
+  const markReady = (gate) => {
+    pending.delete(gate);
+    tryHide();
+  };
+  const useReady = (gate, ready) => {
+    useEffect(() => {
+      if (ready) markReady(gate);
+    }, [ready, gate]);
+  };
+  const pendingGates = () => Array.from(pending);
+  tryHide();
+  return { markReady, useReady, pendingGates };
+}
+export {
+  createSplashGate
+};

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@rific/splash-gate",
+  "version": "0.1.0",
+  "description": "Name every async condition an Expo app's first screen depends on (theme, fonts, saved preferences, auth, ...) and hold the splash screen up until all of them report ready — instead of hand-rolling a fresh ad hoc gate per project",
+  "keywords": [
+    "expo",
+    "expo-splash-screen",
+    "splash-screen",
+    "app-loading",
+    "font-loading"
+  ],
+  "homepage": "https://github.com/jayrdeaton/Expo-Splash-Gate#readme",
+  "bugs": {
+    "url": "https://github.com/jayrdeaton/Expo-Splash-Gate/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayrdeaton/Expo-Splash-Gate.git"
+  },
+  "license": "MIT",
+  "author": "Jay Deaton",
+  "sideEffects": false,
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "react-native": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/__tests__"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "build:watch": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "fix": "eslint --fix",
+    "lint": "eslint",
+    "prepublishOnly": "npm run build",
+    "release": "git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "test": "jest",
+    "test:watch": "jest --watchAll",
+    "typecheck": "tsc --noEmit",
+    "preversion": "npm run lint && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.0.0",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-package-json": "^1.0.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "expo-splash-screen": "^57.0.5",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "prettier": "^3.8.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.0.0",
+    "ts-jest": "^29.4.9",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3"
+  },
+  "peerDependencies": {
+    "expo-splash-screen": ">=0.30.0",
+    "react": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__mocks__/expo-splash-screen.ts

@@ -0,0 +1,3 @@
+export const hideAsync = jest.fn(() => Promise.resolve())
+export const preventAutoHideAsync = jest.fn(() => Promise.resolve(true))
+export const setOptions = jest.fn()

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { SplashGate } from './splashGate'
+export { createSplashGate } from './splashGate'

package/src/splashGate.ts

@@ -0,0 +1,60 @@
+import * as SplashScreen from 'expo-splash-screen'
+import { useEffect } from 'react'
+
+export type SplashGate<T extends string> = {
+  // Marks one named gate ready. Safe to call more than once for the same gate (a no-op after the
+  // first) and safe to call for every gate in any order: the splash only ever hides once every
+  // gate this instance was created with has been marked, and only ever hides once. For a gate that
+  // only resolves via a one-shot callback (a library's own `onReady` prop, a promise `.then`),
+  // call this directly there. For a gate that's already a plain boolean (state from a hook like
+  // `useFonts`, or your own derived condition), useReady below is that same call written once.
+  markReady: (gate: T) => void
+  // Marks `gate` ready once `ready` becomes true. Bound to this gate instance, so there's nothing
+  // to pass but the two things that actually vary at the call site.
+  useReady: (gate: T, ready: boolean) => void
+  // Gate names still outstanding, in no particular order. For a debug log or a "why is this still
+  // up" check during development, not something app code should need to branch on.
+  pendingGates: () => T[]
+}
+
+// One named condition per thing your first screen actually depends on (a loaded theme, a loaded
+// font, a hydrated preference, a resolved auth check, ...) instead of hand-rolling a fresh ad hoc
+// module-scope gate per project. Call this once, up front, with every gate the app needs, then
+// call `markReady`/`useReady` for each one from wherever it actually resolves. The splash stays up
+// (you're still responsible for `SplashScreen.preventAutoHideAsync()` yourself, before this runs)
+// until every named gate has reported in, then it hides itself exactly once, so nothing your
+// app's first screen shows can ever be caught mid-load, wrong-then-corrected, a beat behind the
+// rest.
+export function createSplashGate<T extends string>(gates: readonly T[]): SplashGate<T> {
+  const pending = new Set<T>(gates)
+  let hidden = false
+
+  const tryHide = () => {
+    if (hidden || pending.size > 0) return
+    hidden = true
+    void SplashScreen.hideAsync()
+  }
+
+  const markReady = (gate: T) => {
+    pending.delete(gate)
+    tryHide()
+  }
+
+  const useReady = (gate: T, ready: boolean) => {
+    // markReady isn't in this dep array. It's this closure's own stable reference (one per
+    // createSplashGate call), not a per-render value, so there's nothing to gain by re-running
+    // this effect if it somehow changed identity.
+    useEffect(() => {
+      if (ready) markReady(gate)
+    }, [ready, gate])
+  }
+
+  const pendingGates = () => Array.from(pending)
+
+  // Nothing to wait for (called with an empty list, or every gate was already satisfied some
+  // other way). Hide right away instead of leaving the splash up forever with nothing left that
+  // could ever call markReady again.
+  tryHide()
+
+  return { markReady, useReady, pendingGates }
+}