create-foldkit-app 0.27.3 → 0.28.0

package/dist/templates/examples/charting/src/githubApi.ts

@@ -0,0 +1,271 @@
+import {
+  Array,
+  Context,
+  Data,
+  Effect,
+  Layer,
+  Number,
+  Option,
+  Schema as S,
+  Schedule,
+} from 'effect'
+import { HttpClient, HttpClientRequest } from 'effect/unstable/http'
+
+import { fetchJson, isSuccessfulStatus, makeUrl } from './http'
+
+// CONSTANT
+
+const GITHUB_REPOSITORY_API = 'https://api.github.com/repos/foldkit/foldkit'
+const HTTP_ACCEPTED = 202
+const STARGAZER_PAGE_SIZE = 100
+const MAX_STARGAZER_PAGES = 10
+const STAT_MAX_RETRIES = 1
+const STAT_RETRY_DELAY = '2 seconds' as const
+const RELEASE_PAGE_SIZE = 100
+
+// SCHEMA
+
+export const GitHubRepositoryResponse = S.Struct({
+  stargazers_count: S.Number,
+  forks_count: S.Number,
+  watchers_count: S.Number,
+  open_issues_count: S.Number,
+  pushed_at: S.String,
+  default_branch: S.String,
+})
+
+export const GitHubContributorResponse = S.Struct({
+  login: S.String,
+  contributions: S.Number,
+  avatar_url: S.OptionFromOptional(S.String),
+})
+export type GitHubContributorResponse = typeof GitHubContributorResponse.Type
+
+export const GitHubIssueResponse = S.Struct({
+  pull_request: S.OptionFromOptional(S.Unknown),
+})
+
+export const GitHubPullRequestResponse = S.Struct({
+  id: S.Number,
+})
+
+export const GitHubReleaseResponse = S.Struct({
+  published_at: S.OptionFromOptional(S.String),
+})
+
+export const GitHubStargazerResponse = S.Struct({
+  starred_at: S.String,
+})
+
+export const GitHubCommitActivityResponse = S.Struct({
+  week: S.Number,
+  total: S.Number,
+})
+
+// SERVICE
+
+export type GitHubStatResult<A> = Readonly<{
+  data: Option.Option<A>
+  warnings: ReadonlyArray<string>
+}>
+
+type GitHubApiShape = Readonly<{
+  fetchRepository: Effect.Effect<typeof GitHubRepositoryResponse.Type, Error>
+  fetchContributors: Effect.Effect<
+    ReadonlyArray<typeof GitHubContributorResponse.Type>,
+    Error
+  >
+  fetchIssues: Effect.Effect<
+    ReadonlyArray<typeof GitHubIssueResponse.Type>,
+    Error
+  >
+  fetchPullRequests: Effect.Effect<
+    ReadonlyArray<typeof GitHubPullRequestResponse.Type>,
+    Error
+  >
+  fetchReleases: (
+    yearCutoffMilliseconds: number,
+  ) => Effect.Effect<ReadonlyArray<typeof GitHubReleaseResponse.Type>, Error>
+  fetchStargazers: (
+    stargazerCount: number,
+  ) => Effect.Effect<ReadonlyArray<typeof GitHubStargazerResponse.Type>, Error>
+  fetchCommitActivity: Effect.Effect<
+    GitHubStatResult<ReadonlyArray<typeof GitHubCommitActivityResponse.Type>>,
+    never
+  >
+}>
+
+export class GitHubApi extends Context.Service<GitHubApi, GitHubApiShape>()(
+  'charting/GitHubApi',
+) {}
+
+class GitHubStatsPending extends Data.TaggedError('GitHubStatsPending') {}
+class GitHubStatError extends Data.TaggedError('GitHubStatError') {}
+
+const fetchOptionalGitHubStat =
+  (client: HttpClient.HttpClient) =>
+  <A, I>(schema: S.Codec<A, I>) =>
+  (path: string, label: string): Effect.Effect<GitHubStatResult<A>, never> => {
+    const url = `${GITHUB_REPOSITORY_API}${path}`
+
+    const attempt: Effect.Effect<
+      GitHubStatResult<A>,
+      GitHubStatsPending
+    > = Effect.gen(function* () {
+      const response = yield* client
+        .execute(HttpClientRequest.get(url))
+        .pipe(Effect.mapError(() => new GitHubStatError()))
+
+      if (response.status === HTTP_ACCEPTED) {
+        return yield* Effect.fail(new GitHubStatsPending())
+      }
+
+      if (!isSuccessfulStatus(response.status)) {
+        return {
+          data: Option.none<A>(),
+          warnings: [`${label} returned HTTP ${response.status}.`],
+        }
+      }
+
+      const data = yield* response.json.pipe(
+        Effect.flatMap(json => S.decodeUnknownEffect(schema)(json)),
+        Effect.option,
+      )
+
+      return Option.match(data, {
+        onNone: () => ({
+          data: Option.none<A>(),
+          warnings: [`${label} returned an unexpected response shape.`],
+        }),
+        onSome: (value): GitHubStatResult<A> => ({
+          data: Option.some(value),
+          warnings: [],
+        }),
+      })
+    }).pipe(
+      Effect.catchTag('GitHubStatError', () =>
+        Effect.succeed({
+          data: Option.none<A>(),
+          warnings: [`${label} is unavailable right now.`],
+        }),
+      ),
+    )
+
+    return attempt.pipe(
+      Effect.retry({
+        while: error => error._tag === 'GitHubStatsPending',
+        schedule: Schedule.spaced(STAT_RETRY_DELAY),
+        times: STAT_MAX_RETRIES,
+      }),
+      Effect.catchTag('GitHubStatsPending', () =>
+        Effect.succeed({
+          data: Option.none<A>(),
+          warnings: [`${label} is still being prepared by GitHub.`],
+        }),
+      ),
+    )
+  }
+
+export const GitHubApiLive: Layer.Layer<
+  GitHubApi,
+  never,
+  HttpClient.HttpClient
+> = Layer.effect(
+  GitHubApi,
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const fetch_ = fetchJson(client)
+    const fetchStat_ = fetchOptionalGitHubStat(client)
+    return {
+      fetchRepository: fetch_(GitHubRepositoryResponse)(GITHUB_REPOSITORY_API),
+      fetchContributors: fetch_(S.Array(GitHubContributorResponse))(
+        makeUrl(`${GITHUB_REPOSITORY_API}/contributors`, {
+          per_page: '100',
+          anon: 'false',
+        }),
+      ),
+      fetchIssues: fetch_(S.Array(GitHubIssueResponse))(
+        makeUrl(`${GITHUB_REPOSITORY_API}/issues`, {
+          state: 'open',
+          per_page: '100',
+        }),
+      ),
+      fetchPullRequests: fetch_(S.Array(GitHubPullRequestResponse))(
+        makeUrl(`${GITHUB_REPOSITORY_API}/pulls`, {
+          state: 'open',
+          per_page: '100',
+        }),
+      ),
+      fetchReleases: (yearCutoffMilliseconds: number) => {
+        const fetchPage = (page: number) =>
+          fetch_(S.Array(GitHubReleaseResponse))(
+            makeUrl(`${GITHUB_REPOSITORY_API}/releases`, {
+              per_page: `${RELEASE_PAGE_SIZE}`,
+              page: `${page}`,
+            }),
+          )
+
+        const fetchFrom = (
+          page: number,
+          accumulated: ReadonlyArray<typeof GitHubReleaseResponse.Type>,
+        ): Effect.Effect<
+          ReadonlyArray<typeof GitHubReleaseResponse.Type>,
+          Error
+        > =>
+          fetchPage(page).pipe(
+            Effect.flatMap(releases =>
+              Array.match(releases, {
+                onEmpty: () => Effect.succeed(accumulated),
+                onNonEmpty: releases => {
+                  const withinYear = Array.filter(releases, release =>
+                    Option.exists(
+                      release.published_at,
+                      publishedAt =>
+                        Date.parse(publishedAt) >= yearCutoffMilliseconds,
+                    ),
+                  )
+
+                  const nextAccumulated = Array.appendAll(
+                    accumulated,
+                    withinYear,
+                  )
+                  const hitCutoff =
+                    Array.length(withinYear) < Array.length(releases)
+                  const isLastPage = Array.length(releases) < RELEASE_PAGE_SIZE
+
+                  if (!hitCutoff && !isLastPage) {
+                    return fetchFrom(Number.increment(page), nextAccumulated)
+                  }
+                  return Effect.succeed(nextAccumulated)
+                },
+              }),
+            ),
+          )
+
+        return fetchFrom(1, [])
+      },
+      fetchStargazers: (stargazerCount: number) => {
+        const pageCount = Math.min(
+          MAX_STARGAZER_PAGES,
+          Math.ceil(stargazerCount / STARGAZER_PAGE_SIZE),
+        )
+        return Effect.forEach(
+          Array.range(1, Math.max(1, pageCount)),
+          page =>
+            fetch_(S.Array(GitHubStargazerResponse))(
+              makeUrl(`${GITHUB_REPOSITORY_API}/stargazers`, {
+                per_page: `${STARGAZER_PAGE_SIZE}`,
+                page: `${page}`,
+              }),
+              { Accept: 'application/vnd.github.star+json' },
+            ),
+          { concurrency: 'unbounded' },
+        ).pipe(Effect.map(Array.flatten))
+      },
+      fetchCommitActivity: fetchStat_(S.Array(GitHubCommitActivityResponse))(
+        '/stats/commit_activity',
+        'Commit activity',
+      ),
+    }
+  }),
+)

package/dist/templates/examples/charting/src/http.ts

@@ -0,0 +1,50 @@
+import { Effect, Record as Record_, Schema as S } from 'effect'
+import { HttpClient, HttpClientRequest } from 'effect/unstable/http'
+
+// CONSTANT
+
+const HTTP_OK_MIN = 200
+const HTTP_OK_MAX = 299
+
+// HTTP
+
+export const isSuccessfulStatus = (status: number): boolean =>
+  status >= HTTP_OK_MIN && status <= HTTP_OK_MAX
+
+export const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : `${error}`
+
+export const makeUrl = (
+  url: string,
+  params: Readonly<Record<string, string>>,
+): string => {
+  const searchParams = new URLSearchParams(params)
+  return `${url}?${searchParams.toString()}`
+}
+
+export const encodePackageName = (packageName: string): string =>
+  encodeURIComponent(packageName)
+
+export const fetchJson =
+  (client: HttpClient.HttpClient) =>
+  <A, I>(schema: S.Codec<A, I>) =>
+  (
+    url: string,
+    headers: Readonly<Record<string, string>> = Record_.empty(),
+  ): Effect.Effect<A, Error> =>
+    Effect.gen(function* () {
+      const request = HttpClientRequest.get(url).pipe(
+        HttpClientRequest.setHeaders(headers),
+      )
+      const response = yield* client.execute(request)
+
+      if (!isSuccessfulStatus(response.status)) {
+        return yield* Effect.fail(
+          new Error(`GET ${url} returned HTTP ${response.status}.`),
+        )
+      }
+
+      return yield* S.decodeUnknownEffect(schema)(yield* response.json).pipe(
+        Effect.mapError(error => new Error(errorMessage(error))),
+      )
+    })

package/dist/templates/examples/charting/src/init.test.ts

@@ -0,0 +1,14 @@
+import { Array } from 'effect'
+import { expect, test } from 'vitest'
+
+import { FetchTelemetry } from './command'
+import { init } from './init'
+
+test('seeds loading state and queues a telemetry fetch', () => {
+  const [model, commands] = init()
+
+  expect(model.telemetry._tag).toBe('Loading')
+  expect(
+    Array.some(commands, command => command.name === FetchTelemetry.name),
+  ).toBe(true)
+})

package/dist/templates/examples/charting/src/init.ts

@@ -0,0 +1,29 @@
+import { Option } from 'effect'
+import { Runtime } from 'foldkit'
+
+import { RadioGroup } from '@foldkit/ui'
+
+import { FetchTelemetry } from './command'
+import type { Message } from './message'
+import { Model, TelemetryAsyncData } from './model'
+import {
+  CHART_MODE_RADIO_GROUP_ID,
+  PACKAGE_RADIO_GROUP_ID,
+  PERIOD_RADIO_GROUP_ID,
+} from './radioGroups'
+
+export const init: Runtime.ApplicationInit<Model, Message> = () => [
+  {
+    telemetry: TelemetryAsyncData.Loading(),
+    chartMode: 'Adoption',
+    chartModeRadioGroup: RadioGroup.init({ id: CHART_MODE_RADIO_GROUP_ID }),
+    selectedPackageId: 'Core',
+    packageRadioGroup: RadioGroup.init({ id: PACKAGE_RADIO_GROUP_ID }),
+    period: 'LastSixteenWeeks',
+    periodRadioGroup: RadioGroup.init({ id: PERIOD_RADIO_GROUP_ID }),
+    maybeChartHostId: Option.none(),
+    maybeChartError: Option.none(),
+    maybeSelectedDatumId: Option.none(),
+  },
+  [FetchTelemetry()],
+]

package/dist/templates/examples/charting/src/main.fixtures.ts

@@ -0,0 +1,162 @@
+import { Option } from 'effect'
+
+import { RadioGroup } from '@foldkit/ui'
+
+import {
+  ContributorSummary,
+  DependencyEdge,
+  PackageSnapshot,
+  RepositorySnapshot,
+  Telemetry,
+  WeeklyDownloads,
+  WeeklyTelemetry,
+} from './domain'
+import { Model, TelemetryAsyncData } from './model'
+import {
+  CHART_MODE_RADIO_GROUP_ID,
+  PACKAGE_RADIO_GROUP_ID,
+  PERIOD_RADIO_GROUP_ID,
+} from './radioGroups'
+
+export const sampleTelemetry = Telemetry.make({
+  fetchedAt: Date.UTC(2026, 5, 22, 12, 0, 0),
+  repository: RepositorySnapshot.make({
+    stars: 342,
+    forks: 18,
+    watchers: 342,
+    openIssues: 12,
+    openPullRequests: 3,
+    visibleContributors: 9,
+    pushedAt: '2026-06-21T19:20:00Z',
+    defaultBranch: 'main',
+  }),
+  packages: [
+    PackageSnapshot.make({
+      id: 'Core',
+      npmName: 'foldkit',
+      displayName: 'foldkit',
+      role: 'runtime',
+      latestVersion: '0.115.0',
+      publishedAt: '2026-06-20T12:00:00Z',
+      totalDownloads: 1200,
+      lastWeekDownloads: 160,
+      dependencyCount: 1,
+      downloadsByWeek: [
+        WeeklyDownloads.make({ weekStart: '2026-06-01', downloads: 110 }),
+        WeeklyDownloads.make({ weekStart: '2026-06-08', downloads: 130 }),
+        WeeklyDownloads.make({ weekStart: '2026-06-15', downloads: 160 }),
+      ],
+    }),
+    PackageSnapshot.make({
+      id: 'Ui',
+      npmName: '@foldkit/ui',
+      displayName: '@foldkit/ui',
+      role: 'components',
+      latestVersion: '0.115.0',
+      publishedAt: '2026-06-20T12:00:00Z',
+      totalDownloads: 820,
+      lastWeekDownloads: 95,
+      dependencyCount: 1,
+      downloadsByWeek: [
+        WeeklyDownloads.make({ weekStart: '2026-06-01', downloads: 70 }),
+        WeeklyDownloads.make({ weekStart: '2026-06-08', downloads: 90 }),
+        WeeklyDownloads.make({ weekStart: '2026-06-15', downloads: 95 }),
+      ],
+    }),
+  ],
+  weeks: [
+    WeeklyTelemetry.make({
+      weekStart: '2026-06-01',
+      cumulativeStars: 330,
+      commits: 12,
+      releases: 1,
+    }),
+    WeeklyTelemetry.make({
+      weekStart: '2026-06-08',
+      cumulativeStars: 336,
+      commits: 17,
+      releases: 0,
+    }),
+    WeeklyTelemetry.make({
+      weekStart: '2026-06-15',
+      cumulativeStars: 342,
+      commits: 22,
+      releases: 1,
+    }),
+  ],
+  dependencyEdges: [
+    DependencyEdge.make({
+      source: 'Ui',
+      target: 'Core',
+      kind: 'PeerDependency',
+    }),
+  ],
+  topContributors: [
+    ContributorSummary.make({
+      login: 'devin',
+      contributions: 42,
+      avatarUrl: Option.none(),
+    }),
+    ContributorSummary.make({
+      login: 'maya',
+      contributions: 21,
+      avatarUrl: Option.none(),
+    }),
+  ],
+  warnings: [],
+})
+
+export const loadingModel = Model.make({
+  telemetry: TelemetryAsyncData.Loading(),
+  chartMode: 'Adoption',
+  chartModeRadioGroup: RadioGroup.init({ id: CHART_MODE_RADIO_GROUP_ID }),
+  selectedPackageId: 'Core',
+  packageRadioGroup: RadioGroup.init({ id: PACKAGE_RADIO_GROUP_ID }),
+  period: 'LastSixteenWeeks',
+  periodRadioGroup: RadioGroup.init({ id: PERIOD_RADIO_GROUP_ID }),
+  maybeChartHostId: Option.none(),
+  maybeChartError: Option.none(),
+  maybeSelectedDatumId: Option.none(),
+})
+
+export const readyModel = Model.make({
+  ...loadingModel,
+  telemetry: TelemetryAsyncData.Success({ data: sampleTelemetry }),
+  maybeChartHostId: Option.some('test-chart-host'),
+})
+
+export const mockGitHubRepository = {
+  stargazers_count: 342,
+  forks_count: 18,
+  watchers_count: 342,
+  open_issues_count: 15,
+  pushed_at: '2026-06-21T19:20:00Z',
+  default_branch: 'main',
+}
+
+export const mockNpmDownloads = {
+  downloads: [
+    { day: '2026-06-01', downloads: 10 },
+    { day: '2026-06-02', downloads: 12 },
+    { day: '2026-06-08', downloads: 20 },
+    { day: '2026-06-15', downloads: 30 },
+  ],
+}
+
+export const mockNpmPackument = {
+  name: 'foldkit',
+  time: {
+    '0.115.0': '2026-06-20T12:00:00Z',
+  },
+  versions: {
+    '0.115.0': {
+      dependencies: {},
+      peerDependencies: {
+        effect: '^4.0.0',
+      },
+    },
+  },
+  'dist-tags': {
+    latest: '0.115.0',
+  },
+}

package/dist/templates/examples/charting/src/message.ts

@@ -0,0 +1,23 @@
+import { Schema as S } from 'effect'
+import { defineMessageUnion } from 'foldkit/message'
+
+import { RadioGroup } from '@foldkit/ui'
+
+import { Telemetry } from './domain'
+
+export const Message = defineMessageUnion({
+  GotChartModeRadioGroupMessage: { message: RadioGroup.Message },
+  GotPackageRadioGroupMessage: { message: RadioGroup.Message },
+  GotPeriodRadioGroupMessage: { message: RadioGroup.Message },
+  ClickedRefresh: {},
+  ClickedRetry: {},
+  ClickedChartDatum: { datumId: S.String },
+  SucceededFetchTelemetry: { telemetry: Telemetry },
+  FailedFetchTelemetry: { error: S.String },
+  SucceededMountChart: { hostId: S.String },
+  FailedMountChart: { reason: S.String },
+  SucceededSyncChart: {},
+  FailedSyncChart: { reason: S.String },
+})
+
+export type Message = typeof Message.Type

package/dist/templates/examples/charting/src/model.ts

@@ -0,0 +1,22 @@
+import { Schema as S } from 'effect'
+import { AsyncData } from 'foldkit'
+
+import { RadioGroup } from '@foldkit/ui'
+
+import { ChartMode, PackageId, Period, Telemetry } from './domain'
+
+export const TelemetryAsyncData = AsyncData.Schema(Telemetry, S.String)
+
+export const Model = S.Struct({
+  telemetry: TelemetryAsyncData.schema,
+  chartMode: ChartMode,
+  chartModeRadioGroup: RadioGroup.Model,
+  selectedPackageId: PackageId,
+  packageRadioGroup: RadioGroup.Model,
+  period: Period,
+  periodRadioGroup: RadioGroup.Model,
+  maybeChartHostId: S.Option(S.String),
+  maybeChartError: S.Option(S.String),
+  maybeSelectedDatumId: S.Option(S.String),
+})
+export type Model = typeof Model.Type

package/dist/templates/examples/charting/src/npmApi.ts

@@ -0,0 +1,75 @@
+import { Context, Effect, Layer, Schema as S } from 'effect'
+import { HttpClient } from 'effect/unstable/http'
+
+import type { PackageSpec } from './domain'
+import { encodePackageName, fetchJson } from './http'
+
+// CONSTANT
+
+const NPM_DOWNLOADS_API = 'https://api.npmjs.org/downloads/range/last-year'
+const NPM_REGISTRY_API = 'https://registry.npmjs.org'
+
+// SCHEMA
+
+export const NpmDownloadDay = S.Struct({
+  day: S.String,
+  downloads: S.Number,
+})
+
+export const NpmDownloadsResponse = S.Struct({
+  downloads: S.Array(NpmDownloadDay),
+})
+
+export const NpmVersionMetadata = S.Struct({
+  dependencies: S.OptionFromOptional(S.Record(S.String, S.String)),
+  peerDependencies: S.OptionFromOptional(S.Record(S.String, S.String)),
+})
+export type NpmVersionMetadata = typeof NpmVersionMetadata.Type
+
+export const NpmPackument = S.Struct({
+  name: S.String,
+  time: S.Record(S.String, S.String),
+  versions: S.Record(S.String, NpmVersionMetadata),
+  'dist-tags': S.Struct({
+    latest: S.String,
+  }),
+})
+
+// SERVICE
+
+type NpmApiShape = Readonly<{
+  fetchPackage: (spec: PackageSpec) => Effect.Effect<
+    Readonly<{
+      downloads: typeof NpmDownloadsResponse.Type
+      packument: typeof NpmPackument.Type
+    }>,
+    Error
+  >
+}>
+
+export class NpmApi extends Context.Service<NpmApi, NpmApiShape>()(
+  'charting/NpmApi',
+) {}
+
+export const NpmApiLive: Layer.Layer<NpmApi, never, HttpClient.HttpClient> =
+  Layer.effect(
+    NpmApi,
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const fetch_ = fetchJson(client)
+      return {
+        fetchPackage: (spec: PackageSpec) =>
+          Effect.all(
+            {
+              downloads: fetch_(NpmDownloadsResponse)(
+                `${NPM_DOWNLOADS_API}/${encodePackageName(spec.npmName)}`,
+              ),
+              packument: fetch_(NpmPackument)(
+                `${NPM_REGISTRY_API}/${encodePackageName(spec.npmName)}`,
+              ),
+            },
+            { concurrency: 'unbounded' },
+          ),
+      }
+    }),
+  )

package/dist/templates/examples/charting/src/radioGroups.ts

@@ -0,0 +1,11 @@
+import { RadioGroup } from '@foldkit/ui'
+
+import type { ChartMode, PackageId, Period } from './domain'
+
+export const CHART_MODE_RADIO_GROUP_ID = 'chart-mode'
+export const PACKAGE_RADIO_GROUP_ID = 'package'
+export const PERIOD_RADIO_GROUP_ID = 'period'
+
+export const ChartModeRadioGroup = RadioGroup.create<ChartMode>()
+export const PackageRadioGroup = RadioGroup.create<PackageId>()
+export const PeriodRadioGroup = RadioGroup.create<Period>()