feat(tailordb,resolver)!: object-literal descriptor API and record-level hooks/validate

[dqn]

Add createTable and resolver field descriptors as an alternative object-literal syntax for defining TailorDB types and resolver input/output fields. Move TailorDB hooks and validators from field level to record level.

Usage

// TailorDB type with createTable (object-literal fields)
const order = createTable(
  "Order",
  {
    name: { kind: "string" },
    quantity: { kind: "int", optional: true, index: true },
    status: { kind: "enum", values: ["pending", "shipped"] },
    address: {
      kind: "object",
      fields: {
        city: { kind: "string" },
        zip: { kind: "string" },
      },
    },
    ...timestampFields(),
  },
  {
    permission: unsafeAllowAllTypePermission,
    hooks: {
      create: ({ data }) => ({
        ...data,
        createdAt: new Date(),
        updatedAt: new Date(),
      }),
      update: ({ data }) => ({
        ...data,
        updatedAt: new Date(),
      }),
    },
    validate: [
      [({ data }) => data.quantity >= 0, "Quantity must be non-negative"],
      ({ data }) => data.name.length > 0,
    ],
  },
);

// Resolver with descriptor fields (mixable with fluent API)
const resolver = createResolver({
  name: "addNumbers",
  operation: "query",
  input: {
    a: { kind: "int" },
    b: { kind: "int" },
  },
  output: { kind: "int" },
  body: ({ input }) => input.a + input.b,
});

Main Changes

• Add createTable object-literal API for TailorDB type definitions with full descriptor support (all scalar kinds, enum, nested object, serial, relation, permissions, indices)
• Add ResolverFieldDescriptor for resolver input/output fields, allowing { kind: "string" } syntax alongside fluent t.string() fields
• Breaking: Remove field-level .hooks() and .validate() from TailorDB field builders and descriptors
• Breaking: createTable type-level hooks / validate options now receive ({ data, user }) with the full record. Hooks must return a complete record (spread incoming data to keep unchanged fields)
• Breaking: db.fields.timestamps() / timestampFields() no longer installs automatic create/update hooks. Populate createdAt / updatedAt via a record-level hook
• Add generated metadata flag to timestamp fields so the Kysely plugin emits Generated<Timestamp> and the seed hook auto-fills values
• Deduplicate kindToFieldType mapping and resolveResolverFieldMap into a shared descriptor.ts module
• Runtime validation: reject unknown descriptor kinds, malformed passthrough fields, invalid decimal scale, and empty/duplicate enum values
• Emit record-level hooks/validators end-to-end via the platform's new TailorDBType.TypeHook / TailorDBType.TypeValidate proto fields, with full snapshot / diff support in the migration system

Notes

• Breaking change for SDK users: field-level hooks/validate and the auto timestamp hooks must be migrated to record-level callbacks

[changeset-bot]

🦋 Changeset detected

Latest commit: a34ce7c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@tailor-platform/sdk	Major
@tailor-platform/create-sdk	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@tailor-platform/create-sdk@905

commit: 216ef75

[claude]

📖 Docs Consistency Check

⚠️ Inconsistencies Found

File	Issue	Suggested Fix
packages/sdk/docs/services/tailordb.md	New createTable API is not documented	Add section documenting createTable object-literal syntax as alternative to db.type()
packages/sdk/docs/services/resolver.md	New descriptor syntax for resolver fields is not documented	Add section documenting { kind: "string" } syntax as alternative to t.string()
CLAUDE.md	Code Patterns section only mentions db.type()	Update to mention createTable as an alternative
example/ directory	No examples demonstrate new APIs	Consider adding example files showing createTable and resolver descriptor usage

Details

1. TailorDB Documentation (packages/sdk/docs/services/tailordb.md)

What the implementation adds:

• createTable(name, { fields }) - Object-literal API exported from @tailor-platform/sdk (packages/sdk/src/configure/services/index.ts:4)
• Supports field descriptors like { kind: "string" }, { kind: "int", optional: true }, etc.
• Full feature parity with db.type() including hooks, validation, relations, indices, permissions

What the docs say:

• Only documents the fluent API: db.type(), db.string(), db.int(), etc.
• No mention of createTable or descriptor syntax anywhere in the file

Example from PR description:

const order = createTable("Order", {
  fields: {
    name: { kind: "string" },
    quantity: { kind: "int", optional: true, index: true },
    status: { kind: "enum", values: ["pending", "shipped"] },
  },
  permission: unsafeAllowAllTypePermission,
});

Suggested section location: After "Type Definition" section (line 17), add a new section titled "Alternative: Object-Literal Syntax (createTable)"

---

2. Resolver Documentation (packages/sdk/docs/services/resolver.md)

What the implementation adds:

• ResolverFieldDescriptor type for resolver input/output fields (packages/sdk/src/configure/services/resolver/descriptor.ts:57-68)
• Allows { kind: "string" } syntax as alternative to t.string()
• Can be mixed with fluent API fields in the same resolver

What the docs say:

• Only documents fluent API: t.int(), t.string(), t.object(), etc. (lines 84-121)
• Section "Input/Output Schemas" (line 104) states: "Define input/output schemas using methods of t object"
• No mention of descriptor syntax

Example from PR description:

const resolver = createResolver({
  name: "addNumbers",
  operation: "query",
  input: {
    a: { kind: "int" },
    b: { kind: "int" },
  },
  output: { kind: "int" },
  body: ({ input }) => input.a + input.b,
});

Suggested section location: After "Input/Output Schemas" intro (line 106), add subsection "Object-Literal Descriptor Syntax"

---

3. CLAUDE.md

What the docs say:

• Line 44: example/tailordb/*.ts - Model definitions with db.type()
• No mention of createTable alternative

Suggested fix:
Update line 44 to:

- `example/tailordb/*.ts` - Model definitions with `db.type()` or `createTable`

Or add to "Non-obvious Rules and Gotchas" section if there are any caveats about the new API.

---

4. Example Files (example/ directory)

What exists:

• All TailorDB types use fluent API: db.type(...) (e.g., example/tailordb/customer.ts)
• All resolvers use fluent API: t.string(), t.int(), etc. (e.g., example/resolvers/add.ts)

What's missing:

• No example demonstrating createTable
• No example demonstrating descriptor syntax in resolvers

Note from PR description:

"No impact on existing db.type() / t.*() APIs"

The old APIs still work, but examples showing the new alternatives would help users understand both options.

---

Recommended Actions

1. Add documentation for createTable in packages/sdk/docs/services/tailordb.md:

   • Show basic usage with field descriptors
   • Explain when to use object-literal vs fluent API (e.g., PR notes that hook typing is less precise in descriptors)
   • Document all supported descriptor options (optional, array, hooks, validate, index, unique, serial, relation, etc.)

2. Add documentation for descriptor syntax in packages/sdk/docs/services/resolver.md:

   • Show that descriptors can be mixed with fluent API
   • Document supported descriptor types (string, int, float, bool, uuid, decimal, date, datetime, time, enum, object)
   • Note any limitations vs fluent API

3. Update CLAUDE.md to mention both API styles

4. Consider adding example files (optional but recommended):

   • example/tailordb/descriptor-example.ts using createTable
   • example/resolvers/descriptor-example.ts using field descriptors

---

[claude]

📖 Docs Consistency Check

⚠️ Inconsistencies Found

File	Issue	Suggested Fix
packages/sdk/docs/services/tailordb.md	Missing createTable() API documentation	Add section documenting the object-literal descriptor API as an alternative to db.type()
packages/sdk/docs/services/tailordb.md	Missing timestampFields() helper	Document the timestampFields() helper function and its usage
packages/sdk/docs/services/resolver.md	Missing descriptor syntax for input/output fields	Add section showing { kind: "string" } syntax alongside fluent API examples
CLAUDE.md	Code Patterns section only mentions db.type()	Add createTable() as an alternative pattern with reference to examples
example/ directory	No examples using new APIs	Add at least one example file demonstrating createTable() and resolver descriptor syntax

Details

1. TailorDB createTable() API (packages/sdk/docs/services/tailordb.md)

What the implementation does:

• packages/sdk/src/configure/services/tailordb/createTable.ts:469-504 - Exports createTable() function that accepts object-literal field descriptors as an alternative to the fluent db.type() API
• packages/sdk/src/configure/services/index.ts:4 - Exports createTable from the main SDK package
• JSDoc example in the implementation shows:

  export const user = createTable("User", {
    name: { kind: "string" },
    email: { kind: "string", unique: true },
    role: { kind: "enum", values: ["MANAGER", "STAFF"] },
    ...timestampFields(),
  });

What the documentation says:

• The TailorDB documentation only documents db.type() with the fluent API
• No mention of createTable() anywhere in the docs
• The "Type Definition" section (lines 17-61) only shows the db.type() pattern

Impact:
Users won't know that the object-literal descriptor API exists as an alternative style for defining TailorDB types.

2. TailorDB timestampFields() helper (packages/sdk/docs/services/tailordb.md)

What the implementation does:

• packages/sdk/src/configure/services/tailordb/createTable.ts:516-530 - Exports timestampFields() helper that returns standard createdAt/updatedAt fields with auto-hooks
• packages/sdk/src/configure/services/index.ts:5 - Exports timestampFields from the main SDK package
• Can be used with both createTable() and db.type() via spread syntax

What the documentation says:

• The docs show ...db.fields.timestamps() (line 357-358) as the pattern for timestamp fields
• No mention of timestampFields() helper

Impact:
Users using createTable() won't know about the timestampFields() helper designed for the descriptor API. The existing db.fields.timestamps() is for the fluent API.

3. Resolver descriptor syntax (packages/sdk/docs/services/resolver.md)

What the implementation does:

• packages/sdk/src/configure/services/resolver/descriptor.ts:1-212 - Implements ResolverFieldDescriptor type system supporting { kind: "string" } syntax
• packages/sdk/src/configure/services/resolver/resolver.ts:79-82 - Documents that input/output fields accept both fluent API and object-literal descriptors, and both can be mixed
• JSDoc example in resolver.ts:106-116 shows:

  input: {
    a: { kind: "int", description: "First number" },
    b: { kind: "int", description: "Second number" },
  },
  output: { kind: "int", description: "Sum" },

What the documentation says:

• packages/sdk/docs/services/resolver.md:84-142 - Only shows fluent API examples with t.string(), t.int(), etc.
• No mention that descriptor syntax { kind: "int" } is supported
• No examples mixing both styles

Impact:
Users won't know they can use descriptor syntax in resolvers, which provides a more concise alternative for simple fields and matches the TailorDB createTable() style.

4. CLAUDE.md Code Patterns section

What the implementation does:

• Adds createTable as a new exported API for defining TailorDB types

What CLAUDE.md says:

• Lines 43: "Model definitions with db.type()" - only mentions the fluent API
• No mention of createTable() as an alternative pattern

Impact:
Claude Code won't know about the new API when helping users write TailorDB models, and won't suggest it as an option.

5. Example files

What the implementation does:

• Adds fully functional createTable() and descriptor APIs

What the examples show:

• example/tailordb/*.ts - All examples use db.type() fluent API only
• example/resolvers/*.ts - All examples use t.string() fluent API only
• No examples demonstrate the new descriptor syntax

Impact:
Users learning from examples won't see the descriptor API in action. The example/ directory is specifically referenced in CLAUDE.md as the source for "working implementations of all patterns."

Recommended Actions

1. Add createTable() section to TailorDB docs - Document the object-literal API with full examples showing all field descriptor types (scalar, enum, object, relations, hooks, validation, etc.)

2. Document timestampFields() helper - Add to TailorDB docs, likely in a "Common Fields" or "Helper Functions" section, showing it works with both createTable() and spread into db.type()

3. Add descriptor syntax section to Resolver docs - Show examples of { kind: "string" } syntax for input/output fields, demonstrate mixing with fluent API

4. Update CLAUDE.md - Add createTable to the Code Patterns section as an alternative to db.type(), update the reference to mention both APIs

5. Add example files - Create at least one TailorDB type using createTable() and one resolver using descriptor syntax in the example/ directory

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 7 additional findings.

[toiroakr]

Hook callback typing in descriptors uses the base scalar type (e.g. string, number) rather than the final output type adjusted for optional/array, due to combinatorial type explosion. Use db.*() fluent API when precise hook typing matters

This is a major issue...
I wonder what we should do... 🤔

[dqn]

Addressed in f987b90 and 47ab17c:

• Added createTable and timestampFields() documentation to tailordb.md
• Added descriptor syntax documentation to resolver.md
• Updated CLAUDE.md code patterns
• Added example/tailordb/product.ts demonstrating the new API

[dqn]

Status: Inline hook typing improvements

What changed

• Hook typing now resolves per-field output type: scalar fields get Hook<O>, array fields get Hook<O[]> (PR body noted this as a known limitation)
• Added overload for inline hook contextual typing (string/int/float/etc. inline callbacks now auto-resolve)
• Inline enum hooks remain a known limitation (see below)

Known limitation: inline enum hooks

Inline enum descriptor hooks ({ kind: "enum", values: [...], hooks: { ... } }) cannot narrow value to the literal union type. This is a fundamental TypeScript reverse-inference limitation: the generic V in EnumDescriptor<V> is not in a direct inference position when contextual-typing callbacks inside a mapped object parameter.

Working alternatives (both tested):

1. options.hooks.<field> — declare the enum without hooks, then provide hooks via the third argument:

createTable(
  "Test",
  { role: { kind: "enum", values: ["ADMIN", "USER"] } },
  {
    hooks: {
      role: {
        create: ({ value }) => {
          // value: "ADMIN" | "USER" | null  ✅
          return value ?? "USER";
        },
      },
    },
  },
);

2. Fluent API — db.enum(...).hooks(...):

createTable("Test", {
  role: db.enum(["ADMIN", "USER"]).hooks({
    create: ({ value }) => {
      // value: "ADMIN" | "USER" | null  ✅
      return value ?? "USER";
    },
  }),
});

[dqn]

Status: waiting on the platform side to add record-level hooks / validate fields to TailorDBTypeSchema / TailorDBType_SchemaSchema in the protobuf. The remaining items in "Follow-up TODOs" (parser / bundler / apply transform) are SDK-side work that follows once the protobuf lands.

[dqn]

Hook callback typing in descriptors uses the base scalar type ... rather than the final output type adjusted for optional/array, due to combinatorial type explosion.

Fixed in 26f1771 — field-level hooks/validate were removed from descriptors entirely, and the surviving record-level callback receives the full output-typed record so this typing limitation no longer applies.

[dqn]

Let's consider deprecating field-level hooks and validation in createTable.

Fixed in 26f1771 — went one step further and removed field-level hooks/validate from createTable (and from the fluent db.*() field builders), so the only place to define them is now the record-level hooks / validate on the type itself.

[github-actions]

Code Metrics Report (packages/sdk)

	main (b2bd4aa)	#905 (d637ef0)	+/-
Coverage	62.3%	62.4%	+0.0%
Code to Test Ratio	1:0.4	1:0.4	+0.0

Details

  |                    | main (b2bd4aa) | #905 (d637ef0) |  +/-  |
  |--------------------|----------------|----------------|-------|
+ | Coverage           |          62.3% |          62.4% | +0.0% |
  |   Files            |            364 |            366 |    +2 |
  |   Lines            |          12773 |          12976 |  +203 |
+ |   Covered          |           7967 |           8102 |  +135 |
+ | Code to Test Ratio |          1:0.4 |          1:0.4 |  +0.0 |
  |   Code             |          83913 |          85693 | +1780 |
+ |   Test             |          35136 |          36003 |  +867 |

Code coverage of files in pull request scope (67.0% → 67.0%)

Files	Coverage	+/-	Status
packages/sdk/src/cli/commands/deploy/tailordb/index.ts	39.4%	+0.2%	modified
packages/sdk/src/cli/commands/tailordb/migrate/snapshot-manifest.ts	77.2%	-3.0%	modified
packages/sdk/src/cli/commands/tailordb/migrate/snapshot.ts	70.3%	-0.8%	modified
packages/sdk/src/cli/services/tailordb/hooks-validate-bundler.ts	70.1%	-12.5%	modified
packages/sdk/src/cli/shared/skills-installer.ts	93.3%	0.0%	modified
packages/sdk/src/configure/services/resolver/descriptor.ts	94.8%	+94.8%	added
packages/sdk/src/configure/services/resolver/resolver.ts	100.0%	0.0%	modified
packages/sdk/src/configure/services/tailordb/createTable.ts	98.5%	+98.5%	added
packages/sdk/src/configure/services/tailordb/index.ts	0.0%	0.0%	modified
packages/sdk/src/configure/services/tailordb/schema.ts	89.7%	+6.1%	modified
packages/sdk/src/configure/types/type.ts	100.0%	0.0%	modified
packages/sdk/src/parser/service/tailordb/field.ts	61.9%	-33.4%	modified
packages/sdk/src/parser/service/tailordb/hooks-validate-precompiled-expr.ts	75.0%	-25.0%	affected
packages/sdk/src/parser/service/tailordb/schema.ts	76.4%	0.0%	modified
packages/sdk/src/parser/service/tailordb/type-parser.ts	85.3%	-5.0%	modified
packages/sdk/src/plugin/builtin/kysely-type/type-processor.ts	91.7%	0.0%	modified
packages/sdk/src/plugin/builtin/seed/lines-db-processor.ts	0.0%	0.0%	modified
packages/sdk/src/types/tailordb.ts	100.0%	0.0%	modified
packages/sdk/src/utils/test/index.ts	80.0%	-20.0%	modified

SDK Configure Bundle Size

	main (b2bd4aa)	#905 (d637ef0)	+/-
configure-index-size	18KB	25.86KB	7.86KB
dependency-chunks-size	33.52KB	33.42KB	-0.1KB
total-bundle-size	51.51KB	59.28KB	7.77KB

Runtime Performance

	main (b2bd4aa)	#905 (d637ef0)	+/-
Generate Median	2,279ms	2,967ms	688ms
Generate Max	2,294ms	3,096ms	802ms
Apply Build Median	2,317ms	2,997ms	680ms
Apply Build Max	2,453ms	3,072ms	619ms

Type Performance (instantiations)

	main (b2bd4aa)	#905 (d637ef0)	+/-
tailordb-basic	35,130	37,391	2,261
tailordb-optional	3,841	3,511	-330
tailordb-relation	7,428	3,660	-3,768
tailordb-validate	2,566	5,450	2,884
tailordb-hooks	5,767	6,540	773
tailordb-object	12,136	11,806	-330
tailordb-enum	2,462	2,132	-330
resolver-basic	9,424	11,363	1,939
resolver-nested	26,111	27,954	1,843
resolver-array	18,187	20,127	1,940
executor-schedule	4,234	4,234	0
executor-webhook	873	873	0
executor-record	8,166	4,398	-3,768
executor-resolver	4,369	6,458	2,089
executor-operation-function	869	869	0
executor-operation-gql	869	869	0
executor-operation-webhook	888	888	0
executor-operation-workflow	1,714	1,714	0

---

Reported by octocov