TypeScript无法识别对象补全属性？问题分析与修复方案

我有一段TypeScript代码，其中convert函数会确保输出对象的output.file一定是带path的结构，但TypeScript无法识别这个逻辑，导致访问out.output.file.path时报错：

type Convert = {
  input: {
    format: string
    file: {
      path: string
    }
  }
  output: {
    format: string
    file?:
      | { content: Blob } 
      | { path: string }
  }
}

// 期望替换output.file为带path的结构
type OutputMod = {
  output: {
    file: {
      path: string
    }
  }
}

function convert<T extends Convert>(props: T) {
  const out = cloneOptions<T>(props)

  if (!out.output.file || !('path' in out.output.file)) {
    out.output.file = { path: 'foo.pdf' }
  }

  return out
}

const out = convert({
  input: {
    format: 'pdf',
    file: {
      path: 'input.pdf'
    }
  },
  output: {
    format: 'png',
    file: {
      content: new Blob(['...'])
    }
  }
})

out.output.file.path // 此处TypeScript报错

尝试过的方案及问题 #

1. 尝试用嵌套属性Omit的思路定义返回类型，结果引入了更复杂的错误：

export async function resolveInputForConvertRemoteNode<
  T extends ResolveInputForConvertRemote,
>(
  input: T,
): Promise<
  OmitBy<T, Split<'output'>> & {
    output: { file: { path: string } }
  }
> {
    console.log(input)
    return Promise.resolve(input)
}

2. 尝试给convert函数指定返回类型T & OutputMod，遇到如下错误：

Type 'T' is not assignable to type 'T & OutputMod'.
  Type 'Convert' is not assignable to type 'T & OutputMod'.
    Type 'Convert' is not assignable to type 'T'.
      'Convert' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint 'Convert'.
        Type 'T' is not assignable to type 'OutputMod'.
          Type 'Convert' is not assignable to type 'OutputMod'.
            The types of 'output.file' are incompatible between these types.
              Type '{ content: Blob; } | { path: string; } | undefined' is not assignable to type '{ path: string; }'.
                Type 'undefined' is not assignable to type '{ path: string; }'.(2322)

另外，cloneOptions函数需要关闭noImplicitAny才能运行，想知道有没有优化方式。

解决方案 #

1. 精确定义函数返回类型 #

不要直接用交叉类型T & OutputMod，而是通过Omit+合并类型来覆盖嵌套属性，确保类型精确：

// 定义合并类型，替换output的file结构
type MergeOutputMod<T> = Omit<T, 'output'> & {
  output: Omit<T['output'], 'file'> & {
    file: { path: string }
  }
}

function convert<T extends Convert>(props: T): MergeOutputMod<T> {
  // 这里用类型断言告诉TS，out会被修改为MergeOutputMod<T>类型
  const out = cloneOptions(props) as MergeOutputMod<T>;

  if (!out.output.file || !('path' in out.output.file)) {
    out.output.file = { path: 'foo.pdf' };
  }

  return out;
}

这样定义后，out.output.file.path就不会再报错，TS能正确识别file是必填的带path的对象。

2. 优化cloneOptions函数（无需关闭noImplicitAny） #

原来的cloneOptions因为直接给y赋值{}导致类型错误，我们可以完善类型处理，同时兼容数组和null：

export function cloneOptions<T extends object>(x: T): T {
  // 处理数组
  if (Array.isArray(x)) {
    return x.map(item => cloneOptions(item)) as unknown as T;
  }
  // 处理非对象或null
  if (typeof x !== 'object' || x === null) {
    return x;
  }

  const y = {} as T;
  // 用for...in配合hasOwnProperty确保遍历自身属性
  for (const key in x) {
    if (Object.prototype.hasOwnProperty.call(x, key)) {
      y[key] = cloneOptions(x[key]);
    }
  }
  return y;
}

修改后无需关闭noImplicitAny，同时逻辑更严谨，覆盖了更多边界情况。

3. 为什么T & OutputMod不行？ #

因为T是Convert的子类型，可能包含比Convert更具体的output.file定义，TypeScript无法确认T的output结构能和OutputMod的output兼容，所以抛出类型不匹配的错误。而用MergeOutputMod直接替换output的结构，避免了这种类型冲突。

内容的提问来源于stack exchange，提问作者Lance Pollard