@soda-gql/core 0.1.0 → 0.3.0

package/README.md

@@ -13,21 +13,15 @@ bun add @soda-gql/core
 
 ## Core Concepts
 
-soda-gql uses three main building blocks for constructing GraphQL operations:
+soda-gql uses two main building blocks for constructing GraphQL operations:
 
-### Models
+### Fragments
 
-Reusable type-safe fragments with data normalization. Models define how to select fields from a GraphQL type and optionally transform the result.
-
-### Slices
-
-Domain-specific query/mutation/subscription pieces. Slices are reusable operation fragments that can be composed into complete operations.
+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 that can be executed. There are two types:
-- **Composed Operations**: Built by combining multiple slices
-- **Inline Operations**: Self-contained operations with field selections defined directly
+Complete GraphQL operations (query/mutation/subscription) with field selections. Operations define variables, select fields, and can embed fragments for reusable field selections.
 
 ## Usage
 
@@ -37,85 +31,47 @@ All soda-gql definitions use the `gql.default()` pattern, which is provided by t
 import { gql } from "@/graphql-system";
 ```
 
-### Writing Models
+### Writing Fragments
 
-Models define reusable fragments for a specific GraphQL type:
+Fragments define reusable field selections for a specific GraphQL type:
 
 ```typescript
-export const userModel = gql.default(({ model }, { $var }) =>
-  model.User(
-    { variables: [$var("includeEmail").scalar("Boolean:?")] },
-    ({ f, $ }) => [
-      f.id(),
-      f.name(),
-      f.email({ if: $.includeEmail }),
-    ],
-    (selection) => ({
-      id: selection.id,
-      name: selection.name,
-      email: selection.email,
+export const userFragment = gql.default(({ fragment }, { $var }) =>
+  fragment.User({
+    variables: { ...$var("includeEmail").Boolean("?") },
+    fields: ({ f, $ }) => ({
+      ...f.id(),
+      ...f.name(),
+      ...f.email({ if: $.includeEmail }),
     }),
-  ),
-);
-```
-
-### Writing Slices
-
-Slices define reusable operation fragments:
-
-```typescript
-export const userSlice = gql.default(({ query }, { $var }) =>
-  query.slice(
-    { variables: [$var("userId").scalar("ID:!")] },
-    ({ f, $ }) => [
-      f.user({ id: $.userId })(() => [
-        userModel.fragment({}),
-      ]),
-    ],
-    ({ select }) =>
-      select(["$.user"], (result) =>
-        result.safeUnwrap(([user]) => userModel.normalize(user)),
-      ),
-  ),
+  }),
 );
 ```
 
-### Writing Operations (Composed)
+### Writing Operations
 
-Composed operations combine multiple slices:
+Operations define complete GraphQL queries, mutations, or subscriptions:
 
 ```typescript
 export const getUserQuery = gql.default(({ query }, { $var }) =>
-  query.composed(
-    {
-      operationName: "GetUser",
-      variables: [$var("id").scalar("ID:!")],
-    },
-    ({ $ }) => ({
-      user: userSlice.embed({ userId: $.id }),
+  query.operation({
+    name: "GetUser",
+    variables: { ...$var("id").ID("!") },
+    fields: ({ f, $ }) => ({
+      ...f.user({ id: $.id })(({ f }) => ({ ...f.id(), ...f.name() })),
     }),
-  ),
+  }),
 );
-```
 
-### Writing Operations (Inline)
-
-Inline operations define field selections directly:
-
-```typescript
-export const getUserInline = gql.default(({ query }, { $var }) =>
-  query.inline(
-    {
-      operationName: "GetUserInline",
-      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").ID("!"), ...$var("includeEmail").Boolean("?") },
+    fields: ({ f, $ }) => ({
+      ...f.user({ id: $.id })(({ f }) => ({ ...userFragment.embed({ includeEmail: $.includeEmail }) })),
+    }),
+  }),
 );
 ```
 
@@ -135,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 |
-| `userModel.fragment({})` | Use model fragment |
+| `...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 |
+
+## 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
 
@@ -180,111 +154,84 @@ export const scalar = {
 Extract TypeScript types from soda-gql elements using `$infer`:
 
 ```typescript
-// Model types
-type UserInput = typeof userModel.$infer.input;
-type UserOutputRaw = typeof userModel.$infer.output.raw;
-type UserOutputNormalized = typeof userModel.$infer.output.normalized;
+// 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({ fields: ({ 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 and slices. This is useful for HTTP headers, GraphQL extensions, and application-specific values.
+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 three base properties:
+All metadata types share two base properties:
 
 | Property | Type | Purpose |
 |----------|------|---------|
 | `headers` | `Record<string, string>` | HTTP headers to include with the GraphQL request |
-| `extensions` | `Record<string, unknown>` | GraphQL extensions in the request payload |
 | `custom` | `Record<string, unknown>` | Application-specific values (auth requirements, cache settings, etc.) |
 
 ### Defining Metadata
 
-Metadata can be defined on both slices and operations:
+Metadata is defined on operations:
 
 ```typescript
-// Slice with metadata
-export const userSlice = gql.default(({ query }, { $var }) =>
-  query.slice(
-    {
-      variables: [$var("userId").scalar("ID:!")],
-      metadata: ({ $ }) => ({
-        headers: { "X-Request-ID": "user-query" },
-        custom: { requiresAuth: true, cacheTtl: 300 },
-      }),
-    },
-    ({ f, $ }) => [f.user({ id: $.userId })(({ f }) => [f.id()])],
-    ({ select }) => select(["$.user"], (user) => user),
-  ),
-);
-
-// Operation with metadata (can reference variables and document)
+// Operation with metadata
 export const getUserQuery = gql.default(({ query }, { $var }) =>
-  query.composed(
-    {
-      operationName: "GetUser",
-      variables: [$var("id").scalar("ID:!")],
-      metadata: ({ $, document }) => ({
-        extensions: {
-          trackedVariables: [$var.getInner($.id)],
-        },
-      }),
-    },
-    ({ $ }) => ({
-      user: userSlice.embed({ userId: $.id }),
-    }),
-  ),
-);
-```
-
-### MetadataAdapter
-
-Use `createMetadataAdapter` to customize metadata behavior at the schema level:
-
-```typescript
-import { createMetadataAdapter } from "@soda-gql/core/metadata";
-import { createHash } from "crypto";
-
-export const metadataAdapter = createMetadataAdapter({
-  // Default metadata applied to all operations
-  defaults: {
-    headers: { "X-GraphQL-Client": "soda-gql" },
-  },
-
-  // Transform metadata at build time (e.g., add persisted query hash)
-  transform: ({ document, metadata }) => ({
-    ...metadata,
-    extensions: {
-      ...metadata.extensions,
-      persistedQuery: {
-        version: 1,
-        sha256Hash: createHash("sha256").update(document).digest("hex"),
+  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() })) }),
   }),
-
-  // Custom merge strategy for slice metadata (optional)
-  mergeSliceMetadata: (operationMetadata, sliceMetadataList) => {
-    // Default: shallow merge where operation takes precedence
-    return { ...sliceMetadataList.reduce((acc, s) => ({ ...acc, ...s }), {}), ...operationMetadata };
-  },
-});
+);
 ```
 
-### Metadata Merging
-
-When an operation includes multiple slices, metadata is merged in this order:
-
-1. **Slice metadata** - Merged together (later slices override earlier ones)
-2. **Operation metadata** - Takes precedence over slice metadata
-3. **Schema defaults** - Applied first, overridden by operation/slice values
-
 ## Runtime Exports
 
 The `/runtime` subpath provides utilities for operation registration and retrieval:
@@ -293,7 +240,7 @@ The `/runtime` subpath provides utilities for operation registration and retriev
 import { gqlRuntime } from "@soda-gql/core/runtime";
 
 // Retrieve registered operations (typically handled by build plugins)
-const operation = gqlRuntime.getComposedOperation("canonicalId");
+const operation = gqlRuntime.getOperation("canonicalId");
 ```
 
 ## TypeScript Support

package/dist/adapter.cjs

@@ -0,0 +1,35 @@
+const require_schema = require('./schema-DuWaRhdp.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 { R as Adapter } from "./schema-BElqa12z.cjs";
+import { r as defineScalar } from "./schema-builder-DDfulXP3.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 { R as Adapter } from "./schema-C7q047S0.js";
+import { r as defineScalar } from "./schema-builder-DfyTaFMt.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-BbCrsNkQ.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"}