@soda-gql/core 0.0.9 → 0.2.0

package/README.md

@@ -0,0 +1,247 @@
+# @soda-gql/core
+
+[![npm version](https://img.shields.io/npm/v/@soda-gql/core.svg)](https://www.npmjs.com/package/@soda-gql/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Core GraphQL types and utilities for the soda-gql ecosystem. This package provides the foundational building blocks for writing type-safe GraphQL operations.
+
+## Installation
+
+```bash
+bun add @soda-gql/core
+```
+
+## Core Concepts
+
+soda-gql uses two main building blocks for constructing GraphQL operations:
+
+### Fragments
+
+Reusable type-safe field selections. Fragments define how to select fields from a GraphQL type and can be embedded in operations.
+
+### Operations
+
+Complete GraphQL operations (query/mutation/subscription) with field selections. Operations define variables, select fields, and can embed fragments for reusable field selections.
+
+## Usage
+
+All soda-gql definitions use the `gql.default()` pattern, which is provided by the generated GraphQL system:
+
+```typescript
+import { gql } from "@/graphql-system";
+```
+
+### Writing Fragments
+
+Fragments define reusable field selections for a specific GraphQL type:
+
+```typescript
+export const userFragment = gql.default(({ fragment }, { $var }) =>
+  fragment.User(
+    { variables: [$var("includeEmail").scalar("Boolean:?")] },
+    ({ f, $ }) => [
+      f.id(),
+      f.name(),
+      f.email({ if: $.includeEmail }),
+    ],
+  ),
+);
+```
+
+### Writing Operations
+
+Operations define complete GraphQL queries, mutations, or subscriptions:
+
+```typescript
+export const getUserQuery = gql.default(({ query }, { $var }) =>
+  query.operation(
+    {
+      name: "GetUser",
+      variables: [$var("id").scalar("ID:!")],
+    },
+    ({ f, $ }) => [
+      f.user({ id: $.id })(({ f }) => [f.id(), f.name()]),
+    ],
+  ),
+);
+
+// Operation with embedded fragment
+export const getUserWithFragment = gql.default(({ query }, { $var }) =>
+  query.operation(
+    {
+      name: "GetUserWithFragment",
+      variables: [$var("id").scalar("ID:!"), $var("includeEmail").scalar("Boolean:?")],
+    },
+    ({ f, $ }) => [
+      f.user({ id: $.id })(({ f }) => [userFragment.embed({ includeEmail: $.includeEmail })]),
+    ],
+  ),
+);
+```
+
+## Variable Type Syntax
+
+Variables are declared using a string-based type syntax:
+
+| Syntax | Meaning | GraphQL Equivalent |
+|--------|---------|-------------------|
+| `"ID:!"` | Required ID | `ID!` |
+| `"String:?"` | Optional String | `String` |
+| `"Int:![]!"` | Required list of required Int | `[Int!]!` |
+| `"String:![]?"` | Optional list of required Strings | `[String!]` |
+| `"MyInput:!"` | Required custom input type | `MyInput!` |
+
+## Field Selection Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `f.id()` | Basic field selection |
+| `f.posts({ limit: 10 })` | Field with arguments |
+| `f.posts()(({ f }) => [...])` | Nested selection (curried) |
+| `f.id(null, { alias: "uuid" })` | Field with alias |
+| `f.email({ if: $.includeEmail })` | Conditional field |
+| `userFragment.embed({})` | Use fragment fields |
+
+## Defining Custom Scalars
+
+Scalars define the TypeScript types for GraphQL scalar values:
+
+```typescript
+import { defineScalar } from "@soda-gql/core";
+
+export const scalar = {
+  // Built-in scalars
+  ...defineScalar<"ID", string, string>("ID"),
+  ...defineScalar<"String", string, string>("String"),
+  ...defineScalar<"Int", number, number>("Int"),
+  ...defineScalar<"Float", number, number>("Float"),
+  ...defineScalar<"Boolean", boolean, boolean>("Boolean"),
+
+  // Custom scalars - defineScalar<Name, InputType, OutputType>(name)
+  ...defineScalar<"DateTime", string, Date>("DateTime"),
+  ...defineScalar<"JSON", Record<string, unknown>, Record<string, unknown>>("JSON"),
+} as const;
+```
+
+Alternative callback syntax:
+
+```typescript
+export const scalar = {
+  ...defineScalar("DateTime", ({ type }) => ({
+    input: type<string>(),
+    output: type<Date>(),
+    directives: {},
+  })),
+} as const;
+```
+
+## Type Inference
+
+Extract TypeScript types from soda-gql elements using `$infer`:
+
+```typescript
+// Fragment types
+type UserInput = typeof userFragment.$infer.input;
+type UserOutput = typeof userFragment.$infer.output;
+
+// Operation types
+type QueryVariables = typeof getUserQuery.$infer.input;
+type QueryResult = typeof getUserQuery.$infer.output.projected;
+```
+
+## Element Extensions
+
+The `attach()` method allows extending gql elements with custom properties. This is useful for colocating related functionality with fragment or operation definitions.
+
+### Basic Usage
+
+```typescript
+import type { GqlElementAttachment } from "@soda-gql/core";
+
+// Define an attachment
+const myAttachment: GqlElementAttachment<typeof userFragment, "custom", { value: number }> = {
+  name: "custom",
+  createValue: (element) => ({ value: 42 }),
+};
+
+// Attach to a fragment
+export const userFragment = gql
+  .default(({ fragment }) => fragment.User({}, ({ f }) => [f.id(), f.name()]))
+  .attach(myAttachment);
+
+// Access the attached property
+userFragment.custom.value; // 42
+```
+
+### Type Safety
+
+Attachments are fully typed. The returned element includes the new property in its type:
+
+```typescript
+const fragment = gql.default(...).attach({ name: "foo", createValue: () => ({ bar: 1 }) });
+// Type: Fragment<...> & { foo: { bar: number } }
+```
+
+## Metadata
+
+Metadata allows you to attach runtime information to operations. This is useful for HTTP headers and application-specific values.
+
+### Metadata Structure
+
+All metadata types share two base properties:
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `headers` | `Record<string, string>` | HTTP headers to include with the GraphQL request |
+| `custom` | `Record<string, unknown>` | Application-specific values (auth requirements, cache settings, etc.) |
+
+### Defining Metadata
+
+Metadata is defined on operations:
+
+```typescript
+// Operation with metadata
+export const getUserQuery = gql.default(({ query }, { $var }) =>
+  query.operation(
+    {
+      name: "GetUser",
+      variables: [$var("id").scalar("ID:!")],
+      metadata: ({ $, document }) => ({
+        headers: { "X-Request-ID": "user-query" },
+        custom: {
+          requiresAuth: true,
+          cacheTtl: 300,
+          trackedVariables: [$var.getInner($.id)],
+        },
+      }),
+    },
+    ({ f, $ }) => [f.user({ id: $.id })(({ f }) => [f.id(), f.name()])],
+  ),
+);
+```
+
+## Runtime Exports
+
+The `/runtime` subpath provides utilities for operation registration and retrieval:
+
+```typescript
+import { gqlRuntime } from "@soda-gql/core/runtime";
+
+// Retrieve registered operations (typically handled by build plugins)
+const operation = gqlRuntime.getOperation("canonicalId");
+```
+
+## TypeScript Support
+
+This package requires TypeScript 5.x or later for full type inference support.
+
+## Related Packages
+
+- [@soda-gql/cli](../cli) - Command-line interface for code generation
+- [@soda-gql/config](../config) - Configuration management
+- [@soda-gql/runtime](../runtime) - Runtime utilities for operation execution
+- [@soda-gql/tsc-plugin](../tsc-plugin) - TypeScript compiler plugin
+
+## License
+
+MIT

package/dist/adapter.cjs

@@ -0,0 +1,35 @@
+const require_schema = require('./schema-Bip7o0g3.cjs');
+
+//#region packages/core/src/adapter/define-adapter.ts
+/**
+* Helper function for defining a unified adapter with helpers and metadata.
+* Provides type inference for helpers, aggregateFragmentMetadata and schemaLevel.
+*
+* @example
+* ```typescript
+* import { defineAdapter } from "@soda-gql/core/adapter";
+* import type { FragmentMetaInfo, OperationMetadata } from "@soda-gql/core";
+*
+* export const adapter = defineAdapter({
+*   helpers: {
+*     auth: {
+*       requiresLogin: () => ({ requiresAuth: true }),
+*       adminOnly: () => ({ requiresAuth: true, role: "admin" }),
+*     },
+*   },
+*   metadata: {
+*     aggregateFragmentMetadata: (fragments: readonly FragmentMetaInfo<OperationMetadata>[]) =>
+*       fragments.map((m) => m.metadata),
+*     schemaLevel: {
+*       apiVersion: "v2",
+*     },
+*   },
+* });
+* ```
+*/
+const defineAdapter = (adapter) => adapter;
+
+//#endregion
+exports.defineAdapter = defineAdapter;
+exports.defineScalar = require_schema.defineScalar;
+//# sourceMappingURL=adapter.cjs.map

package/dist/adapter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.cjs","names":[],"sources":["../src/adapter/define-adapter.ts"],"sourcesContent":["import type { Adapter } from \"../types/metadata\";\n\n/**\n * Helper function for defining a unified adapter with helpers and metadata.\n * Provides type inference for helpers, aggregateFragmentMetadata and schemaLevel.\n *\n * @example\n * ```typescript\n * import { defineAdapter } from \"@soda-gql/core/adapter\";\n * import type { FragmentMetaInfo, OperationMetadata } from \"@soda-gql/core\";\n *\n * export const adapter = defineAdapter({\n *   helpers: {\n *     auth: {\n *       requiresLogin: () => ({ requiresAuth: true }),\n *       adminOnly: () => ({ requiresAuth: true, role: \"admin\" }),\n *     },\n *   },\n *   metadata: {\n *     aggregateFragmentMetadata: (fragments: readonly FragmentMetaInfo<OperationMetadata>[]) =>\n *       fragments.map((m) => m.metadata),\n *     schemaLevel: {\n *       apiVersion: \"v2\",\n *     },\n *   },\n * });\n * ```\n */\nexport const defineAdapter = <\n  THelpers extends object = object,\n  TFragmentMetadata = unknown,\n  TAggregatedFragmentMetadata = unknown,\n  TSchemaLevel = unknown,\n>(\n  adapter: Adapter<THelpers, TFragmentMetadata, TAggregatedFragmentMetadata, TSchemaLevel>,\n): Adapter<THelpers, TFragmentMetadata, TAggregatedFragmentMetadata, TSchemaLevel> => adapter;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,MAAa,iBAMX,YACoF"}

package/dist/adapter.d.cts

@@ -0,0 +1,35 @@
+import { I as Adapter } from "./schema-DRkKucYe.cjs";
+import { r as defineScalar } from "./schema-builder-8zadflz-.cjs";
+
+//#region packages/core/src/adapter/define-adapter.d.ts
+
+/**
+ * Helper function for defining a unified adapter with helpers and metadata.
+ * Provides type inference for helpers, aggregateFragmentMetadata and schemaLevel.
+ *
+ * @example
+ * ```typescript
+ * import { defineAdapter } from "@soda-gql/core/adapter";
+ * import type { FragmentMetaInfo, OperationMetadata } from "@soda-gql/core";
+ *
+ * export const adapter = defineAdapter({
+ *   helpers: {
+ *     auth: {
+ *       requiresLogin: () => ({ requiresAuth: true }),
+ *       adminOnly: () => ({ requiresAuth: true, role: "admin" }),
+ *     },
+ *   },
+ *   metadata: {
+ *     aggregateFragmentMetadata: (fragments: readonly FragmentMetaInfo<OperationMetadata>[]) =>
+ *       fragments.map((m) => m.metadata),
+ *     schemaLevel: {
+ *       apiVersion: "v2",
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare const defineAdapter: <THelpers extends object = object, TFragmentMetadata = unknown, TAggregatedFragmentMetadata = unknown, TSchemaLevel = unknown>(adapter: Adapter<THelpers, TFragmentMetadata, TAggregatedFragmentMetadata, TSchemaLevel>) => Adapter<THelpers, TFragmentMetadata, TAggregatedFragmentMetadata, TSchemaLevel>;
+//#endregion
+export { defineAdapter, defineScalar };
+//# sourceMappingURL=adapter.d.cts.map

package/dist/adapter.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.cts","names":[],"sources":["../src/adapter/define-adapter.ts"],"sourcesContent":[],"mappings":";;;;;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;;;cAAa,uJAMF,QAAQ,UAAU,mBAAmB,6BAA6B,kBAC1E,QAAQ,UAAU,mBAAmB,6BAA6B"}

package/dist/adapter.d.ts

@@ -0,0 +1,35 @@
+import { I as Adapter } from "./schema-BygZwEX8.js";
+import { r as defineScalar } from "./schema-builder-vwQtCGYI.js";
+
+//#region packages/core/src/adapter/define-adapter.d.ts
+
+/**
+ * Helper function for defining a unified adapter with helpers and metadata.
+ * Provides type inference for helpers, aggregateFragmentMetadata and schemaLevel.
+ *
+ * @example
+ * ```typescript
+ * import { defineAdapter } from "@soda-gql/core/adapter";
+ * import type { FragmentMetaInfo, OperationMetadata } from "@soda-gql/core";
+ *
+ * export const adapter = defineAdapter({
+ *   helpers: {
+ *     auth: {
+ *       requiresLogin: () => ({ requiresAuth: true }),
+ *       adminOnly: () => ({ requiresAuth: true, role: "admin" }),
+ *     },
+ *   },
+ *   metadata: {
+ *     aggregateFragmentMetadata: (fragments: readonly FragmentMetaInfo<OperationMetadata>[]) =>
+ *       fragments.map((m) => m.metadata),
+ *     schemaLevel: {
+ *       apiVersion: "v2",
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare const defineAdapter: <THelpers extends object = object, TFragmentMetadata = unknown, TAggregatedFragmentMetadata = unknown, TSchemaLevel = unknown>(adapter: Adapter<THelpers, TFragmentMetadata, TAggregatedFragmentMetadata, TSchemaLevel>) => Adapter<THelpers, TFragmentMetadata, TAggregatedFragmentMetadata, TSchemaLevel>;
+//#endregion
+export { defineAdapter, defineScalar };
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../src/adapter/define-adapter.ts"],"sourcesContent":[],"mappings":";;;;;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;;;cAAa,uJAMF,QAAQ,UAAU,mBAAmB,6BAA6B,kBAC1E,QAAQ,UAAU,mBAAmB,6BAA6B"}

package/dist/adapter.js

@@ -0,0 +1,34 @@
+import { r as defineScalar } from "./schema-D9wIW5Dl.js";
+
+//#region packages/core/src/adapter/define-adapter.ts
+/**
+* Helper function for defining a unified adapter with helpers and metadata.
+* Provides type inference for helpers, aggregateFragmentMetadata and schemaLevel.
+*
+* @example
+* ```typescript
+* import { defineAdapter } from "@soda-gql/core/adapter";
+* import type { FragmentMetaInfo, OperationMetadata } from "@soda-gql/core";
+*
+* export const adapter = defineAdapter({
+*   helpers: {
+*     auth: {
+*       requiresLogin: () => ({ requiresAuth: true }),
+*       adminOnly: () => ({ requiresAuth: true, role: "admin" }),
+*     },
+*   },
+*   metadata: {
+*     aggregateFragmentMetadata: (fragments: readonly FragmentMetaInfo<OperationMetadata>[]) =>
+*       fragments.map((m) => m.metadata),
+*     schemaLevel: {
+*       apiVersion: "v2",
+*     },
+*   },
+* });
+* ```
+*/
+const defineAdapter = (adapter) => adapter;
+
+//#endregion
+export { defineAdapter, defineScalar };
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":[],"sources":["../src/adapter/define-adapter.ts"],"sourcesContent":["import type { Adapter } from \"../types/metadata\";\n\n/**\n * Helper function for defining a unified adapter with helpers and metadata.\n * Provides type inference for helpers, aggregateFragmentMetadata and schemaLevel.\n *\n * @example\n * ```typescript\n * import { defineAdapter } from \"@soda-gql/core/adapter\";\n * import type { FragmentMetaInfo, OperationMetadata } from \"@soda-gql/core\";\n *\n * export const adapter = defineAdapter({\n *   helpers: {\n *     auth: {\n *       requiresLogin: () => ({ requiresAuth: true }),\n *       adminOnly: () => ({ requiresAuth: true, role: \"admin\" }),\n *     },\n *   },\n *   metadata: {\n *     aggregateFragmentMetadata: (fragments: readonly FragmentMetaInfo<OperationMetadata>[]) =>\n *       fragments.map((m) => m.metadata),\n *     schemaLevel: {\n *       apiVersion: \"v2\",\n *     },\n *   },\n * });\n * ```\n */\nexport const defineAdapter = <\n  THelpers extends object = object,\n  TFragmentMetadata = unknown,\n  TAggregatedFragmentMetadata = unknown,\n  TSchemaLevel = unknown,\n>(\n  adapter: Adapter<THelpers, TFragmentMetadata, TAggregatedFragmentMetadata, TSchemaLevel>,\n): Adapter<THelpers, TFragmentMetadata, TAggregatedFragmentMetadata, TSchemaLevel> => adapter;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,MAAa,iBAMX,YACoF"}