@soda-gql/core 0.1.0 → 0.2.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,83 +31,49 @@ 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(
+export const userFragment = gql.default(({ fragment }, { $var }) =>
+  fragment.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,
-    }),
   ),
 );
 ```
 
-### Writing Slices
+### Writing Operations
 
-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)
-
-Composed operations combine multiple slices:
+Operations define complete GraphQL queries, mutations, or subscriptions:
 
 ```typescript
 export const getUserQuery = gql.default(({ query }, { $var }) =>
-  query.composed(
+  query.operation(
     {
-      operationName: "GetUser",
+      name: "GetUser",
       variables: [$var("id").scalar("ID:!")],
     },
-    ({ $ }) => ({
-      user: userSlice.embed({ userId: $.id }),
-    }),
+    ({ 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(
+// Operation with embedded fragment
+export const getUserWithFragment = gql.default(({ query }, { $var }) =>
+  query.operation(
     {
-      operationName: "GetUserInline",
-      variables: [$var("id").scalar("ID:!")],
+      name: "GetUserWithFragment",
+      variables: [$var("id").scalar("ID:!"), $var("includeEmail").scalar("Boolean:?")],
     },
     ({ f, $ }) => [
-      f.user({ id: $.id })(({ f }) => [
-        f.id(),
-        f.name(),
-      ]),
+      f.user({ id: $.id })(({ f }) => [userFragment.embed({ includeEmail: $.includeEmail })]),
     ],
   ),
 );
@@ -140,7 +100,7 @@ Variables are declared using a string-based type syntax:
 | `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 |
+| `userFragment.embed({})` | Use fragment fields |
 
 ## Defining Custom Scalars
 
@@ -180,111 +140,86 @@ 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({}, ({ 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(
+  query.operation(
     {
-      operationName: "GetUser",
+      name: "GetUser",
       variables: [$var("id").scalar("ID:!")],
       metadata: ({ $, document }) => ({
-        extensions: {
+        headers: { "X-Request-ID": "user-query" },
+        custom: {
+          requiresAuth: true,
+          cacheTtl: 300,
           trackedVariables: [$var.getInner($.id)],
         },
       }),
     },
-    ({ $ }) => ({
-      user: userSlice.embed({ userId: $.id }),
-    }),
+    ({ f, $ }) => [f.user({ id: $.id })(({ f }) => [f.id(), f.name()])],
   ),
 );
 ```
 
-### 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"),
-      },
-    },
-  }),
-
-  // 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 +228,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-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"}