@soda-gql/core 0.2.0 → 0.4.0

package/README.md

@@ -17,11 +17,11 @@ 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.
+Reusable type-safe field selections. Fragments define how to select fields from a GraphQL type and can be spread 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.
+Complete GraphQL operations (query/mutation/subscription) with field selections. Operations define variables, select fields, and can spread fragments for reusable field selections.
 
 ## Usage
 
@@ -36,15 +36,15 @@ import { gql } from "@/graphql-system";
 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 }),
-    ],
-  ),
+export const userFragment = gql.default(({ fragment, $var }) =>
+  fragment.User({
+    variables: { ...$var("includeEmail").Boolean("?") },
+    fields: ({ f, $ }) => ({
+      ...f.id(),
+      ...f.name(),
+      ...f.email({ if: $.includeEmail }),
+    }),
+  }),
 );
 ```
 
@@ -53,29 +53,25 @@ export const userFragment = gql.default(({ fragment }, { $var }) =>
 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()]),
-    ],
-  ),
+export const getUserQuery = gql.default(({ query, $var }) =>
+  query.operation({
+    name: "GetUser",
+    variables: { ...$var("id").ID("!") },
+    fields: ({ 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 })]),
-    ],
-  ),
+// Operation with spread fragment
+export const getUserWithFragment = gql.default(({ query, $var }) =>
+  query.operation({
+    name: "GetUserWithFragment",
+    variables: { ...$var("id").ID("!"), ...$var("includeEmail").Boolean("?") },
+    fields: ({ f, $ }) => ({
+      ...f.user({ id: $.id })(({ f }) => ({ ...userFragment.spread({ includeEmail: $.includeEmail }) })),
+    }),
+  }),
 );
 ```
 
@@ -95,12 +91,30 @@ Variables are declared using a string-based type syntax:
 
 | 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 |
+| `...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.spread({})` | Use fragment fields |
+
+## Understanding the Inject Module
+
+The inject module (`{schema}.inject.ts`) bridges your GraphQL schema with TypeScript types.
+
+**Why hand-written?**
+- Custom scalar types (DateTime, JSON, etc.) need explicit TypeScript type mappings
+- Version-controlled to keep type behavior explicit and reviewable
+
+**What it contains:**
+- `scalar`: TypeScript type definitions for each GraphQL scalar
+
+**Scaffolding:**
+```bash
+bun run soda-gql codegen --emit-inject-template ./src/graphql-system/default.inject.ts
+```
+
+This creates a template with standard scalars (ID, String, Int, Float, Boolean) that you can customize.
 
 ## Defining Custom Scalars
 
@@ -166,7 +180,7 @@ const myAttachment: GqlElementAttachment<typeof userFragment, "custom", { value:
 
 // Attach to a fragment
 export const userFragment = gql
-  .default(({ fragment }) => fragment.User({}, ({ f }) => [f.id(), f.name()]))
+  .default(({ fragment }) => fragment.User({ fields: ({ f }) => ({ ...f.id(), ...f.name() }) }))
   .attach(myAttachment);
 
 // Access the attached property
@@ -201,22 +215,20 @@ 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()])],
-  ),
+export const getUserQuery = gql.default(({ query, $var }) =>
+  query.operation({
+    name: "GetUser",
+    variables: { ...$var("id").ID("!") },
+    metadata: ({ $, document }) => ({
+      headers: { "X-Request-ID": "user-query" },
+      custom: {
+        requiresAuth: true,
+        cacheTtl: 300,
+        trackedVariables: [$var.getInner($.id)],
+      },
+    }),
+    fields: ({ f, $ }) => ({ ...f.user({ id: $.id })(({ f }) => ({ ...f.id(), ...f.name() })) }),
+  }),
 );
 ```
 

package/dist/adapter.cjs

@@ -1,4 +1,4 @@
-const require_schema = require('./schema-Bip7o0g3.cjs');
+const require_schema = require('./schema-DuWaRhdp.cjs');
 
 //#region packages/core/src/adapter/define-adapter.ts
 /**

package/dist/adapter.d.cts

@@ -1,5 +1,5 @@
-import { I as Adapter } from "./schema-DRkKucYe.cjs";
-import { r as defineScalar } from "./schema-builder-8zadflz-.cjs";
+import { R as Adapter } from "./schema-5Vfg289u.cjs";
+import { r as defineScalar } from "./schema-builder-cy5uLVP1.cjs";
 
 //#region packages/core/src/adapter/define-adapter.d.ts
 

package/dist/adapter.d.ts

@@ -1,5 +1,5 @@
-import { I as Adapter } from "./schema-BygZwEX8.js";
-import { r as defineScalar } from "./schema-builder-vwQtCGYI.js";
+import { R as Adapter } from "./schema-DnlCvCK4.js";
+import { r as defineScalar } from "./schema-builder-D_K9ESSn.js";
 
 //#region packages/core/src/adapter/define-adapter.d.ts
 

package/dist/adapter.js

@@ -1,4 +1,4 @@
-import { r as defineScalar } from "./schema-D9wIW5Dl.js";
+import { r as defineScalar } from "./schema-BbCrsNkQ.js";
 
 //#region packages/core/src/adapter/define-adapter.ts
 /**