feat(plugin-activity-guard): add activity entry guards

.changeset/bright-guards-enter.md

@@ -0,0 +1,5 @@
+---
+"@stackflow/plugin-activity-guard": major
+---
+
+Package initial release; Allow programmers to restrict activity entrances via predicates called 'guards'.

extensions/plugin-activity-guard/esbuild.config.js

@@ -0,0 +1,29 @@
+const { context } = require("esbuild");
+const config = require("@stackflow/esbuild-config");
+const pkg = require("./package.json");
+
+const watch = process.argv.includes("--watch");
+const external = Object.keys({
+  ...pkg.dependencies,
+  ...pkg.peerDependencies,
+});
+
+Promise.all([
+  context({
+    ...config({}),
+    format: "cjs",
+    external,
+  }).then((ctx) =>
+    watch ? ctx.watch() : ctx.rebuild().then(() => ctx.dispose()),
+  ),
+  context({
+    ...config({}),
+    format: "esm",
+    outExtension: {
+      ".js": ".mjs",
+    },
+    external,
+  }).then((ctx) =>
+    watch ? ctx.watch() : ctx.rebuild().then(() => ctx.dispose()),
+  ),
+]).catch(() => process.exit(1));

extensions/plugin-activity-guard/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@stackflow/plugin-activity-guard",
+  "version": "0.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/daangn/stackflow.git",
+    "directory": "extensions/plugin-activity-guard"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "yarn build:js && yarn build:dts",
+    "build:dts": "tsc --emitDeclarationOnly",
+    "build:js": "node ./esbuild.config.js",
+    "clean": "rimraf dist",
+    "dev": "yarn build:js --watch && yarn build:dts --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@stackflow/config": "^2.0.0",
+    "@stackflow/core": "^3.0.0",
+    "@stackflow/esbuild-config": "^1.0.3",
+    "@types/node": "^20.14.9",
+    "esbuild": "^0.27.3",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.5.3"
+  },
+  "peerDependencies": {
+    "@stackflow/config": "^2.0.0",
+    "@stackflow/core": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "ultra": {
+    "concurrent": [
+      "dev",
+      "build"
+    ]
+  }
+}

extensions/plugin-activity-guard/src/ActivityGuard.ts

@@ -0,0 +1,88 @@
+import type {
+  InferActivityParams,
+  RegisteredActivityName,
+} from "@stackflow/config";
+import type { NonEmptyArray } from './NonEmptyArray'
+
+export type GuardResolution = {
+  type: "redirect",
+  target: {
+    [ActivityName in RegisteredActivityName]: {
+      activityName: ActivityName,
+      activityParams: InferActivityParams<ActivityName>
+    }
+  }[RegisteredActivityName]
+} | true
+
+export type ActivityGuardFor<ActivityName extends RegisteredActivityName> = (
+  input: {
+    activityName: ActivityName;
+    activityParams: InferActivityParams<ActivityName>;
+  },
+) => GuardResolution;
+
+export type ActivityGuard = {
+  [ActivityName in RegisteredActivityName]: ActivityGuardFor<ActivityName>;
+}[RegisteredActivityName];
+
+export function redirect<ActivityName extends RegisteredActivityName>(
+  activityName: ActivityName,
+  activityParams: InferActivityParams<ActivityName>,
+): GuardResolution {
+  return {
+    type: 'redirect',
+    target: {
+      activityName,
+      activityParams
+    }
+  }
+}
+
+export function all<ActivityName extends RegisteredActivityName>(...guards: NonEmptyArray<ActivityGuardFor<ActivityName>>): ActivityGuardFor<ActivityName> {
+  return (input) => {
+    for (const guard of guards) {
+      const resolution = guard(input);
+
+      if (resolution !== true) {
+        return resolution;
+      }
+    }
+
+    return true;
+  };
+}
+
+export type Target = {
+  [ActivityName in RegisteredActivityName]: {
+    activityName: ActivityName,
+    activityParams: InferActivityParams<ActivityName>
+  }
+}[RegisteredActivityName]
+
+export type Guards = Partial<{
+  [ActivityName in RegisteredActivityName]: ActivityGuardFor<ActivityName>;
+}>;
+
+export function resolveGuards(origin: Target, guards: Guards): {
+  target: Target,
+  blocked: boolean
+} {
+  const guard = guards[origin.activityName];
+
+  if (typeof guard !== "function") return {
+    target: origin,
+    blocked: false
+  };
+
+  const resolution = guard(origin);
+
+  if (resolution === true) return {
+    target: origin,
+    blocked: false
+  };
+
+  return {
+    target: resolveGuards(resolution.target, guards).target,
+    blocked: true
+  }
+}

extensions/plugin-activity-guard/src/NonEmptyArray.ts

@@ -0,0 +1 @@
+export type NonEmptyArray<T> = readonly [T, ...T[]];

extensions/plugin-activity-guard/src/activityGuardPlugin.ts

@@ -0,0 +1,69 @@
+import type { SnapshotEvent, StackflowPlugin } from "@stackflow/core";
+import { resolveGuards, type Guards } from './ActivityGuard';
+
+export interface ActivityGuardPluginOptions {
+  guards: Guards
+}
+
+export function activityGuardPlugin({ guards }: ActivityGuardPluginOptions): StackflowPlugin {
+  return () => ({
+    key: "@stackflow/plugin-activity-guard",
+    overrideInitialEvents({ initialEvents, initInfo }) {
+      if (initInfo.kind === "load") {
+        return initialEvents;
+      }
+
+      const nextEvents: SnapshotEvent[] = []
+
+      for (const event of initialEvents) {
+        if (event.name === "Pushed" || event.name === "Replaced") {
+          const { target, blocked } = resolveGuards(
+            {
+              activityName: event.activityName,
+              activityParams: event.activityParams
+            },
+            guards
+          );
+
+          if (blocked) {
+            nextEvents.push({
+              ...event,
+              activityName: target.activityName,
+              activityParams: target.activityParams
+            });
+
+            return nextEvents;
+          }
+        }
+
+        nextEvents.push(event);
+      }
+
+      return nextEvents;
+    },
+    onBeforePush({ actionParams, actions }) {
+      const { target } = resolveGuards({
+        activityName: actionParams.activityName,
+        activityParams: actionParams.activityParams
+      }, guards)
+
+      actions.overrideActionParams({
+        ...actionParams,
+        activityName: target.activityName,
+        activityParams: target.activityParams
+      });
+    },
+    onBeforeReplace({ actionParams, actions }) {
+      const { target } = resolveGuards({
+        activityName: actionParams.activityName,
+        activityParams: actionParams.activityParams
+      }, guards)
+
+      actions.overrideActionParams({
+        ...actionParams,
+        activityName: target.activityName,
+        activityParams: target.activityParams
+      });
+    },
+  });
+}

extensions/plugin-activity-guard/src/index.ts

@@ -0,0 +1,3 @@
+export * from './activityGuardPlugin.js'
+export * from './NonEmptyArray.js';
+export * from './ActivityGuard.js'

extensions/plugin-activity-guard/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "jsx": "preserve",
+    "module": "preserve",
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist"
+  },
+  "include": ["./src/**/*"]
+}

yarn.lock

@@ -5764,6 +5764,23 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@stackflow/plugin-activity-guard@workspace:extensions/plugin-activity-guard":
+  version: 0.0.0-use.local
+  resolution: "@stackflow/plugin-activity-guard@workspace:extensions/plugin-activity-guard"
+  dependencies:
+    "@stackflow/config": "npm:^2.0.0"
+    "@stackflow/core": "npm:^3.0.0"
+    "@stackflow/esbuild-config": "npm:^1.0.3"
+    "@types/node": "npm:^20.14.9"
+    esbuild: "npm:^0.27.3"
+    rimraf: "npm:^6.1.3"
+    typescript: "npm:^5.5.3"
+  peerDependencies:
+    "@stackflow/config": ^2.0.0
+    "@stackflow/core": ^3.0.0
+  languageName: unknown
+  linkType: soft
+
 "@stackflow/plugin-basic-ui@npm:^1.18.3, @stackflow/plugin-basic-ui@workspace:extensions/plugin-basic-ui":
   version: 0.0.0-use.local
   resolution: "@stackflow/plugin-basic-ui@workspace:extensions/plugin-basic-ui"