@hub3js/core 0.0.0-experimental-03bf1f89-20260602

package/src/mod.ts

@@ -0,0 +1,27 @@
+export type {
+  Actions,
+  RegisteredNamespaces,
+  Store,
+  State,
+  ProviderMetadata,
+  Subscriber,
+  SubscriberCleanUp,
+  Context,
+  CanEagerConnect,
+  FunctionWithContext,
+} from './hub/mod.js';
+export {
+  Hub,
+  Provider,
+  Namespace,
+  createStore,
+  guessProviderStateSelector,
+  namespaceStateSelector,
+} from './hub/mod.js';
+
+export type { ProxiedNamespace, FindProxiedNamespace } from './builders/mod.js';
+export {
+  NamespaceBuilder,
+  ProviderBuilder,
+  ActionBuilder,
+} from './builders/mod.js';

package/src/test-utils/fixtures.ts

@@ -0,0 +1,13 @@
+import type { ProviderConfig, ProviderInfo } from '../hub/store/mod.js';
+
+export const garbageWalletMetaData: ProviderConfig['metadata'] = {
+  name: 'Garbage Wallet',
+  icon: 'https://somewhereininternet.com/icon.svg',
+  extensions: {
+    homepage: 'https://app.rango.exchange',
+  },
+};
+
+export const garbageWalletInfo: ProviderInfo = {
+  metadata: garbageWalletMetaData,
+};

package/src/test-utils/mod.ts

@@ -0,0 +1 @@
+export { garbageWalletMetaData, garbageWalletInfo } from './fixtures.js';

package/src/utils/mod.ts

@@ -0,0 +1,2 @@
+export type { VersionedProvider, VersionedProviders } from './versions.js';
+export { defineVersions, pickVersion } from './versions.js';

package/src/utils/versions.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'vitest';
+
+import { defineVersions, pickVersion } from './versions.js';
+
+describe('Picking versions should work correctly', () => {
+  test("Error on picking a version doesn't exist", () => {
+    const versions = defineVersions().build();
+    expect(() => pickVersion(versions, '1.0.0')).toThrowError();
+  });
+
+  test('Pick the correct version if it exist', () => {
+    const versions = defineVersions()
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .version('0.0.0', {} as any)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .version('1.0.0', {} as any)
+      .build();
+
+    const target = pickVersion(versions, '1.0.0');
+    expect(target).toBeDefined();
+    expect(target[0]).toBe('1.0.0');
+  });
+});

package/src/utils/versions.ts

@@ -0,0 +1,91 @@
+/**
+ * A `[semver, value]` tuple describing one version of a provider implementation.
+ *
+ * Generic over both the version string and the value so consumers can use this
+ * for any kind of versioned provider, not just the `@hub3js/core` Hub.
+ */
+export type VersionedProvider<
+  V extends string = string,
+  T = unknown,
+> = readonly [V, T];
+
+/**
+ * A list of `VersionedProvider` tuples — i.e., the full set of versions one
+ * provider exposes. Kept as a public alias so downstream consumers porting
+ * from `@rango-dev/wallets-core/utils` can keep their existing imports.
+ */
+export type VersionedProviders = readonly VersionedProvider[];
+
+/**
+ * Allowed `targetVersion` values for a given list. When the list is empty
+ * (`T[number][0]` is `never`), fall back to `string` so the runtime
+ * "version not found" guard remains reachable.
+ */
+type AllowedVersion<T extends readonly VersionedProvider[]> = [
+  T[number][0],
+] extends [never]
+  ? string
+  : T[number][0];
+
+/**
+ * Look up a specific version in a `VersionedProviders` list.
+ *
+ * @example
+ * ```ts
+ * const versions = defineVersions()
+ *   .version('1.0.0', myProvider)
+ *   .build();
+ *
+ * const [, provider] = pickVersion(versions, '1.0.0');
+ * ```
+ */
+export function pickVersion<
+  T extends readonly VersionedProvider[],
+  V extends AllowedVersion<T>,
+>(list: T, targetVersion: V): Extract<T[number], readonly [V, unknown]> {
+  if (!targetVersion) {
+    throw new Error(`You should provide a valid semver, e.g 1.0.0.`);
+  }
+
+  const target = list.find(([version]) => version === targetVersion);
+
+  if (!target) {
+    const available = list.map(([version]) => version).join(', ');
+    throw new Error(
+      `Target version "${targetVersion}" hasn't been found. Available versions: ${available}`,
+    );
+  }
+
+  return target as Extract<T[number], readonly [V, unknown]>;
+}
+
+interface VersionsBuilder<T extends readonly VersionedProvider[]> {
+  /**
+   * Register a `[semver, value]` pair. The version string is preserved as a
+   * literal in the resulting type so `pickVersion` can return precise types.
+   */
+  version<const V extends string, P>(
+    semver: V,
+    value: P,
+  ): VersionsBuilder<readonly [...T, readonly [V, P]]>;
+  build(): T;
+}
+
+/**
+ * Fluent builder for a `VersionedProviders` list. Each `.version()` call
+ * accumulates into the inferred type so the final `build()` returns a
+ * precisely-typed tuple of tuples.
+ */
+export function defineVersions(): VersionsBuilder<readonly []> {
+  const make = <T extends readonly VersionedProvider[]>(
+    acc: T,
+  ): VersionsBuilder<T> => ({
+    version: <const V extends string, P>(semver: V, value: P) =>
+      make<readonly [...T, readonly [V, P]]>([
+        ...acc,
+        [semver, value] as const,
+      ] as const),
+    build: () => acc,
+  });
+  return make([] as const);
+}

package/store/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@hub3js/core/store",
+  "type": "module",
+  "main": "../dist/hub/store/mod.js",
+  "module": "../dist/hub/store/mod.js",
+  "types": "../dist/hub/store/mod.d.ts",
+  "sideEffects": false
+}