Cast required to access custom options when defining a custom plugin/feature

Start with packages/table-core/src/types/TableFeatures.ts and compare its published types with the custom-plugin example and custom features guide. Reproduce the TypeScript errors in the linked example, then determine how custom feature options should be exposed without casts or whether the documentation must be corrected. Done means the intended custom-plugin usage type-checks consistently and the guide matches the supported API.

TanStack Table version

9.2.4

Framework/Library version

Vue 3.5.43

Describe the bug and the steps to reproduce it

When defining a custom plugin/feature, a cast is required to access any options that it adds. For example, this is can be observed in an official example for custom plugins--on lines 108 and 119, table.options requires a cast to access onDensityChange. Here's the relevant code for convenience:

  constructTableAPIs: (table) => {
    assignTableAPIs('densityPlugin', table, {
      table_setDensity: {
        fn: (updater: Updater<DensityState>) => {
          const safeUpdater: Updater<DensityState> = (old) => {
            const newState = functionalUpdate(updater, old)
            return newState
          }
          return (table.options as TableOptions_Density).onDensityChange?.(
            safeUpdater,
          )
        },
      },
      table_toggleDensity: {
        fn: (value?: DensityState) => {
          const safeUpdater: Updater<DensityState> = (old) => {
            if (value) return value
            return old === 'lg' ? 'md' : old === 'md' ? 'sm' : 'lg' // cycle through the 3 options
          }
          return (table.options as TableOptions_Density).onDensityChange?.(
            safeUpdater,
          )
        },
      },
    })
  },

In theory, the internal Table_Internal type used in the TableFeature definition should be able to load options added by plugins, but this type is stripped from the published code (I guess using the code from this PR?), so the type exposed to custom plugin authors is the regular Table, which does not come with plugins by default. Interestingly, Table has support for Table<any, any> to load all plugins, but trying to set that on the table in the constructTableAPIs function causes its own type error since that doesn't match the type set by TableFeature.

export const densityPlugin: TableFeature = {
  constructTableAPIs: (table: Table<any, any>) => {
    // can now access table.options.onDensityChange with the correct types, but now this function itself causes a type error:
/*
Type
<TFeatures extends TableFeatures, TData extends RowData>(table: Table<any, any>) => void
is not assignable to type
<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>) => void
*/ 
  }
}

I'm not sure what the best way to solve this is; I see a few possibilities:

• leave it as is; a couple type casts isn't a huge deal.
  • in this case, the docs should be updated--e.g., the custom features guide says "If the TypeScript types are set up correctly, you should have no TypeScript errors when you create the feature object with the new state, options, and instance APIs." but the example code immediately afterwards does not have the cast, so it actually does have TS errors.
• change TableFeature to use a different/new Table_All type that actually gets published
• change TableFeature to accept generic parameters for its own custom options/state/etc.? (not sure we'd have access to the right TFeatures/TData then, though, and I have no idea what that would do to typechecking performance.)

Your Minimal, Reproducible Example - (Sandbox Highly Recommended)

https://tanstack.com/table/latest/docs/framework/react/examples/custom-plugin

Screenshots or Videos (Optional)

No response

Do you intend to try to help solve this bug with your own PR?

None

Terms & Code of Conduct

• I agree to follow this project's Code of Conduct
• I understand that if my bug cannot be reliable reproduced in a debuggable environment, it will probably not be fixed and this issue may even be closed.