@uniflowed/core 0.0.0-alpha.2

package/index.js

@@ -0,0 +1,41 @@
+// @flow
+//
+// Root entry point of `@uniflowed/core`.
+//
+// This module exists for discoverability only. It re-exports, by name, exactly
+// the surface `uf_lib`'s Rust registry promises for the `@uniflowed/core`
+// specifier — the test API and the config entry point. Everything else lives
+// behind a subpath, and subpath imports are the supported entry points:
+// `@uniflowed/core/native` is the one this package implements itself.
+//
+// The two re-exported surfaces are implemented in `@uniflowed/test` and
+// `@uniflowed/config` and reached by specifier, not by relative path: each
+// `packages/*` directory is published as its own npm package, so a relative
+// path into a sibling names a file that exists in this repository and nowhere
+// in an installed tree.
+//
+// There is deliberately no `export *` here. A star re-export forces a bundler
+// to keep the whole module graph reachable from this file, and a whole-surface
+// barrel could not exist anyway: several domains legitimately export the same
+// name (`graphql`, `Image`, `Markdown`, `plan`, `Text`, `contract`, ...).
+
+export type { TestBody, TestOptions } from "@uniflowed/test";
+export {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  fn,
+  it,
+  test,
+} from "@uniflowed/test";
+
+export type {
+  CapabilityJsHost,
+  RuleLevel,
+  TaskDefinition,
+  UniflowedConfig,
+} from "@uniflowed/config";
+export { defineConfig } from "@uniflowed/config";

package/internal/native-runtime.js

@@ -0,0 +1,108 @@
+// @flow
+//
+// Internal to `@uniflowed/core`.
+//
+// This module is deliberately absent from `package.json#exports`, so Node and
+// every bundler that honours the exports map refuse to resolve
+// `@uniflowed/core/internal/native-runtime`. Sibling modules reach it through a
+// relative specifier, which the exports map does not gate.
+//
+// It exists so the "native runtime required" message is defined in exactly one
+// place, and so the phantom carriers behind the package's opaque types share a
+// single documented convention.
+
+/**
+ * Specifier of the shipped subpath a binding belongs to, for example
+ * `@uniflowed/core/effect`.
+ */
+export type ModuleSpecifier = string;
+
+/**
+ * Phantom carrier for an opaque handle the native runtime owns.
+ *
+ * `Name` is a distinct string literal per handle, which keeps two unrelated
+ * handles from unifying even inside the module that defines them.
+ */
+export type NativeHandle<Name extends string> = { readonly __ufNative: Name };
+
+/**
+ * Phantom carrier for an opaque handle with an invariant type parameter.
+ *
+ * `T` sits behind a writable property, which is precisely what invariance
+ * means: `Handle<Dog>` is neither a subtype nor a supertype of `Handle<Animal>`.
+ */
+export type NativeHandleInvariant<Name extends string, T> = {
+  readonly __ufNative: Name,
+  __ufValue: T,
+};
+
+/**
+ * Phantom carrier for an opaque handle with a covariant type parameter.
+ *
+ * `T` only ever appears in a return position, so `Handle<Dog>` stays assignable
+ * to `Handle<Animal>` — the guarantee a `+T` sigil makes to callers.
+ */
+export type NativeHandleCovariant<Name extends string, out T> = {
+  readonly __ufNative: Name,
+  readonly __ufValue: () => T,
+};
+
+/**
+ * Phantom carrier for a handle with two covariant type parameters.
+ *
+ * Same guarantee as `NativeHandleCovariant`, for a handle that tracks two
+ * things at once — a fiber's success and failure types, say.
+ */
+export type NativeHandleCovariant2<Name extends string, out A, out B> = {
+  readonly __ufNative: Name,
+  readonly __ufFirst: () => A,
+  readonly __ufSecond: () => B,
+};
+
+/**
+ * Phantom carrier for a handle with three covariant type parameters.
+ *
+ * An effect tracks what it produces, how it fails, and what it needs; each sits
+ * behind a function that returns it, which is what makes all three covariant
+ * rather than merely declared so.
+ */
+export type NativeHandleCovariant3<Name extends string, out A, out B, out C> = {
+  readonly __ufNative: Name,
+  readonly __ufFirst: () => A,
+  readonly __ufSecond: () => B,
+  readonly __ufThird: () => C,
+};
+
+/**
+ * Raised when a `@uniflowed/*` binding is reached outside the uf native runtime.
+ *
+ * The message names both the subpath and the binding, so a caller sees
+ * `@uniflowed/core/effect: effect() requires the uf native runtime` rather than
+ * a generic failure.
+ */
+export class NativeRuntimeRequiredError extends Error {
+  /** Subpath the binding belongs to, e.g. `@uniflowed/core/effect`. */
+  moduleSpecifier: ModuleSpecifier;
+  /** Binding that was reached, e.g. `effect` or `Dialog.Root`. */
+  binding: string;
+
+  constructor(moduleSpecifier: ModuleSpecifier, binding: string) {
+    super(`${moduleSpecifier}: ${binding}() requires the uf native runtime`);
+    this.name = "NativeRuntimeRequiredError";
+    this.moduleSpecifier = moduleSpecifier;
+    this.binding = binding;
+  }
+}
+
+/**
+ * Raise `NativeRuntimeRequiredError` for one binding.
+ *
+ * Returns `empty`, Flow's bottom type, so a call site can `return` it from a
+ * function of any declared return type without weakening that type to `any` or
+ * `mixed`. Every shipped binding raises on *call*; importing a subpath stays
+ * free of side effects so bundlers can drop the modules an application never
+ * touches.
+ */
+export function nativeRuntimeRequired(moduleSpecifier: ModuleSpecifier, binding: string): empty {
+  throw new NativeRuntimeRequiredError(moduleSpecifier, binding);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@uniflowed/core",
+  "version": "0.0.0-alpha.2",
+  "description": "Shared native-runtime bridge for the Unified Toolchain for Flow (React).",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/core"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./native": "./internal/native-runtime.js"
+  },
+  "files": [
+    "index.js",
+    "internal/*.js"
+  ],
+  "dependencies": {
+    "@uniflowed/config": "0.0.0-alpha.2",
+    "@uniflowed/test": "0.0.0-alpha.2"
+  }
+}