feat: pickTableColumns utility function and update documentation

[productdevbook]

closes: #3034

This pull request introduces a new utility function and updates the documentation to reflect its usage. The most important changes include the addition of the pickTableColumns function and the corresponding updates to the documentation.

New utility function:

• drizzle-orm/src/utils.ts: Added the pickTableColumns function, which allows selecting specific columns from a table based on the provided criteria.

Documentation updates:

• docs/table-introspect-api.md: Updated the documentation to include an example of how to use the pickTableColumns function with the pgTable function.

[lasseklovstad]

You should add a test if the types get correctly infered through the db.select(pickTableColumns(table, {...})).from(table). I don't think they do now?

[productdevbook]

@lasseklovstad

I was going to write a test but I can't run the project locally, not even pnpm. We are currently using the same code in our own project.

Details

❯ pnpm i    
Scope: all 9 workspace projects
Lockfile is up to date, resolution step is skipped
Packages: +2043
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 2043, reused 2009, downloaded 0, added 0, done
node_modules/.pnpm/[email protected]/node_modules/cpu-features: Running install script...
node_modules/.pnpm/[email protected]/node_modules/better-sqlite3: Running install script...
node_modules/.pnpm/[email protected]/node_modules/better-sqlite3: Running install script...
node_modules/.pnpm/[email protected]/node_modules/sqlite3: Running install script...
node_modules/.pnpm/[email protected]/node_modules/sqlite3: Running install script, failed in 1.4s
.../[email protected]/node_modules/sqlite3 install$ prebuild-install -r …
│ prebuild-install warn This package does not support N-API version …
│ prebuild-install warn install No prebuilt binaries found (target=u…
│ gyp info it worked if it ends with ok
│ gyp info using [email protected]
│ gyp info using [email protected] | darwin | arm64
│ (node:12495) [DEP0060] DeprecationWarning: The `util._extend` API …
│ (Use `node --trace-deprecation ...` to show where the warning was …
│ gyp info find Python using Python version 3.13.1 found at "/opt/ho…
│ gyp info spawn /opt/homebrew/opt/[email protected]/bin/python3.13
│ gyp info spawn args [
│ gyp info spawn args   '/Users/productdevbook/Documents/GitHub/dev/…
│ gyp info spawn args   'binding.gyp',
│ gyp info spawn args   '-f',
│ gyp info spawn args   'make',
│ gyp info spawn args   '-I',
│ gyp info spawn args   '/Users/productdevbook/Documents/GitHub/dev/…
│ gyp info spawn args   '-I',
│ gyp info spawn args   '/Users/productdevbook/Documents/GitHub/dev/…
│ gyp info spawn args   '-I',
│ gyp info spawn args   '/Users/productdevbook/Library/Caches/node-g…
│ gyp info spawn args   '-Dlibrary=shared_library',
│ gyp info spawn args   '-Dvisibility=default',
│ gyp info spawn args   '-Dnode_root_dir=/Users/productdevbook/Libra…
│ gyp info spawn args   '-Dnode_gyp_dir=/Users/productdevbook/Docume…
│ gyp info spawn args   '-Dnode_lib_file=/Users/productdevbook/Libra…
│ gyp info spawn args   '-Dmodule_root_dir=/Users/productdevbook/Doc…
│ gyp info spawn args   '-Dnode_engine=v8',
│ gyp info spawn args   '--depth=.',
│ gyp info spawn args   '--no-parallel',
│ gyp info spawn args   '--generator-output',
│ gyp info spawn args   'build',
│ gyp info spawn args   '-Goutput_dir=.'
│ gyp info spawn args ]
│ Traceback (most recent call last):
│   File "/Users/productdevbook/Documents/GitHub/dev/dev-drizzle-orm…
│     import gyp  # noqa: E402
│     ^^^^^^^^^^
│   File "/Users/productdevbook/Documents/GitHub/dev/dev-drizzle-orm…
│     import gyp.input
│   File "/Users/productdevbook/Documents/GitHub/dev/dev-drizzle-orm…
│     from distutils.version import StrictVersion
│ ModuleNotFoundError: No module named 'distutils'
│ gyp ERR! configure error 
│ gyp ERR! stack Error: `gyp` failed with exit code: 1
│ gyp ERR! stack     at ChildProcess.onCpExit (/Users/productdevbook…
│ gyp ERR! stack     at ChildProcess.emit (node:events:507:28)
│ gyp ERR! stack     at ChildProcess._handle.onexit (node:internal/c…
│ gyp ERR! System Darwin 24.2.0
│ gyp ERR! command "/Users/productdevbook/.nvm/versions/node/v23.6.0…
│ gyp ERR! cwd /Users/productdevbook/Documents/GitHub/dev/dev-drizzl…
│ gyp ERR! node -v v23.6.0
│ gyp ERR! node-gyp -v v8.4.1
│ gyp ERR! not ok 
└─ Failed in 1.4s at /Users/productdevbook/Documents/GitHub/dev/dev-drizzle-orm/node_modules/.pnpm/[email protected]/node_modules/sqlite3
node_modules/.pnpm/[email protected]/node_modules/workerd: Running postinstall script...
 ELIFECYCLE  Command failed with exit code 1.