@squidcloud/cli 1.0.449 → 1.0.451

package/dist/resources/claude/skills/squid-development/SKILL.md

@@ -18,7 +18,7 @@ Squid is a backend-as-a-service platform that provides:
 - **[client.md](reference/client.md)** → client SDK, initialization, setup, auth, login, tokens, OAuth, appId, region, environmentId, apiKey, authProvider, getToken, setAuthProvider, Squid client, frontend, collection, executeFunction, executeFunctionWithHeaders, getWebhookUrl, externalAuth, saveAuthCode, getAccessToken, storage, uploadFile, downloadUrl, queues, produce, consume, distributed locks, acquireLock, withLock, web, aiSearch, getUrlContent, createShortUrl, jobs, getJob, awaitJob, observability, metrics, reportMetric, queryMetrics, notifications, publishNotification, observeNotifications
 - **[console.md](reference/console.md)** → Squid Console, web UI, organizations, applications, AI Studio, knowledge bases, integrations, monitoring, logs, API keys, secrets, testing, debugging, profile settings, management API keys
 - **[ai.md](reference/ai.md)** → AI agents, chat, ask, askWithAnnotations, askAsync, askWithVoiceResponse, transcribeAndChat, transcribeAndAsk, knowledge bases, RAG, embeddings, image generation, audio, transcription, text-to-speech, TTS, connectedAgents, connectedIntegrations, connectedKnowledgeBases, @aiFunction, @secureAiAgent, @secureAiQuery, memory, memoryOptions, voiceOptions, OpenAI, Anthropic, Gemini, Grok, DALL-E, Whisper, MCP, @mcpServer, @mcpTool, executeAiQuery, executeAiApiCall, extraction, createPdf, upsert agent, listAgents
-- **[databases.md](reference/databases.md)** → collections, documents, queries, subscriptions, snapshots, insert, update, delete, CRUD, real-time, dereference, pagination, transactions, query operators, eq, neq, gt, gte, lt, lte, like, in, nin, arrayIncludesSome, arrayIncludesAll, sortBy, limit, join queries, OR queries, @trigger, native queries, SQL, MongoDB, Elasticsearch, incrementInPath, decrementInPath, watch changes, doc()
+- **[databases.md](reference/databases.md)** → collections, documents, queries, subscriptions, snapshots, insert, update, delete, CRUD, real-time, dereference, pagination, transactions, query operators, eq, neq, gt, gte, lt, lte, like, in, nin, arrayIncludesSome, arrayIncludesAll, sortBy, limit, join queries, OR queries, @trigger, native queries, SQL, MongoDB, Elasticsearch, incrementInPath, decrementInPath, watch changes, doc(), projectFields, field projection, __docId__, __id
 - **[backend.md](reference/backend.md)** → SquidService, @executable, @webhook, @trigger, TriggerRequest, @scheduler, @limits, rate limiting, quotas, decorators, backend functions, WebhookRequest, CronExpression, cron, file handling, SquidFile, getUserAuth, isAuthenticated, assertIsAuthenticated, createWebhookResponse, this.squid, this.secrets, @clientConnectionStateHandler, CLI, squid init, squid start, squid deploy, squid build, project structure
 - **[security.md](reference/security.md)** → security rules, @secureDatabase, @secureCollection, @secureTopic, @secureStorage, @secureApi, @secureNativeQuery, @secureAiQuery, @secureAiAgent, @secureDistributedLock, @secureGraphQL, QueryContext, MutationContext, isSubqueryOf, affectsPath, permissions, authorization, row-level security, role-based access
 - **[admin.md](reference/admin.md)** → ManagementClient, management API keys, organizations, applications, programmatic management, CI/CD, automation, integrations admin, secrets admin, upsertIntegration, discoverDataConnectionSchema, testDataConnection, createOrganization, createApplication

package/dist/resources/claude/skills/squid-development/reference/backend.md

@@ -393,8 +393,8 @@ export class MyService extends SquidService {
 Handle client connection and disconnection events.
 
 ```typescript
-import { SquidService, clientConnectionStateHandler, ClientConnectionState } from '@squidcloud/backend';
-import { ClientId } from '@squidcloud/client';
+import { SquidService, clientConnectionStateHandler } from '@squidcloud/backend';
+import { ClientConnectionState, ClientId } from '@squidcloud/client';
 
 export class MyService extends SquidService {
   @clientConnectionStateHandler()

package/dist/resources/claude/skills/squid-development/reference/databases.md

@@ -11,6 +11,7 @@ Squid provides database functionality similar to Firestore but more powerful, wi
 - OR Queries
 - Join Queries
 - Dereference
+- Field Projection
 - Pagination
 - Watch Changes
 - Transactions
@@ -314,6 +315,144 @@ const userData = await users.query()
 // - You need DocumentReference methods like .update() or .delete()
 ```
 
+## Field Projection
+
+Return only specific fields from queries to reduce bandwidth and improve performance.
+
+```typescript
+// Basic usage
+const results = await users.query()
+  .projectFields(['name', 'email'])
+  .dereference()
+  .snapshot();
+
+// Works with all query methods
+const results = await users.query()
+  .eq('status', 'active')
+  .sortBy('name')
+  .limit(50)
+  .projectFields(['name', 'email', 'status'])
+  .dereference()
+  .snapshot();
+```
+
+### Always-Included Fields
+
+These fields are **always** included in results regardless of projection:
+
+| Field | Present On | Description |
+|-------|------------|-------------|
+| `__docId__` | All integrations | JSON-stringified document identifier |
+| `__id` | `built_in_db` only | Primary key value |
+
+For **composite primary keys**, individual key fields are automatically spread to the top level:
+```typescript
+// Document with composite PK (pk1, pk2)
+// Result includes: { name: 'Alice', __docId__: '{"pk1":"a","pk2":1}', pk1: 'a', pk2: 1 }
+```
+
+### Nested Fields
+
+Use dot notation for nested paths:
+```typescript
+const results = await users.query()
+  .projectFields(['name', 'address.city', 'address.zip'])
+  .dereference()
+  .snapshot();
+// Result: { name: 'Alice', address: { city: 'NYC', zip: '10001' } }
+// Other address fields NOT included
+```
+
+### Validation Rules
+
+**Filter fields must be projected:**
+```typescript
+// ERROR: Cannot filter by 'email' not in projectFields
+users.query().eq('email', 'test@example.com').projectFields(['name']);
+
+// CORRECT: Include filter field
+users.query().eq('email', 'test@example.com').projectFields(['name', 'email']);
+```
+
+**Sort fields must be projected:**
+```typescript
+// ERROR: Cannot sort by 'email' not in projectFields
+users.query().sortBy('email').projectFields(['name']);
+
+// CORRECT: Include sort field
+users.query().sortBy('email').projectFields(['name', 'email']);
+```
+
+**Exception:** `__docId__` can always be used for filtering/sorting without being in projection:
+```typescript
+// ALLOWED: __docId__ is always available
+users.query().where('__docId__', '>=', 'user_100').projectFields(['name']);
+users.query().sortBy('__docId__').projectFields(['name']);
+```
+
+**Composite conditions must use projected fields:**
+```typescript
+// ERROR: Cannot filter by 'email' not in projectFields
+users.query().projectFields(['name']).addCompositeCondition([{ fieldName: 'email', operator: '>=', value: 'a' }]);
+
+// ALLOWED: __docId__ works without projection
+users.query().projectFields(['name']).addCompositeCondition([{ fieldName: '__docId__', operator: '>=', value: 'a' }]);
+```
+
+**Calling projectFields twice:** Second call must be a subset of the first:
+```typescript
+// ALLOWED: ['name'] is subset of ['name', 'age', 'email']
+users.query().projectFields(['name', 'age', 'email']).projectFields(['name']);
+
+// ERROR: 'email' was not in first projection
+users.query().projectFields(['name', 'age']).projectFields(['name', 'email']);
+```
+
+**Cloning:** `projectFields` returns a cloned QueryBuilder - original is unmodified:
+```typescript
+const base = collection.query().where('age', '>=', 18);
+const projected = base.projectFields(['name']);  // Returns clone
+// base still returns all fields, projected returns only 'name'
+```
+
+### Empty Array Behavior
+
+| Integration | Behavior |
+|-------------|----------|
+| `built_in_db` | Returns documents with only `__docId__` and `__id`, no user fields |
+| External DBs | **Throws error** - must specify at least one field |
+
+```typescript
+// built_in_db: returns { __docId__: '...', __id: '...' }
+await builtInCollection.query().projectFields([]).snapshot();
+
+// External DB: throws error
+await postgresCollection.query().projectFields([]); // Error!
+```
+
+### Edge Cases
+
+- **Non-existent fields:** Silently ignored, no error thrown
+- **Duplicate fields:** Handled gracefully, no duplication in results
+- **Including `__id` explicitly:** Not duplicated if already auto-included
+- **Optimistic updates:** Local updates respect the projection - document store only contains projected fields. Multiple subscriptions with different projections maintain isolated views of the same document.
+
+### Without dereference()
+
+When not using `dereference()`, you get `DocumentReference` objects. Access projected data via `.data`:
+```typescript
+const refs = await users.query().projectFields(['name']).snapshot();
+console.log(refs[0].data.name);  // Projected data on .data property
+```
+
+### Works With
+
+- One-time queries (`.snapshot()`)
+- Real-time subscriptions (`.snapshots()`)
+- Pagination (`.paginate()`)
+- Join queries
+- All database integrations (MongoDB, PostgreSQL, MySQL, ClickHouse, MS SQL, built_in_db)
+
 ## Pagination
 
 ```typescript

package/dist/resources/user-build.webpack.config.js

@@ -21,6 +21,15 @@ module.exports = function (env, argv) {
       'bufferutil': 'commonjs bufferutil',
       'utf-8-validate': 'commonjs utf-8-validate',
     },
+    // Suppress warnings from dependencies that use dynamic requires.
+    // These are typically dev dependencies used during build and don't affect runtime.
+    ignoreWarnings: [
+      { module: /tsoa/ },
+      { module: /@tsoa\/cli/ },
+      { module: /handlebars/ },
+      { module: /typescript/ },
+      { module: /yargs/ },
+    ],
     output: {
       path: path.resolve(process.cwd(), 'dist'),
       filename: 'index.js',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/cli",
-  "version": "1.0.449",
+  "version": "1.0.451",
   "description": "The Squid CLI",
   "main": "dist/index.js",
   "scripts": {
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@squidcloud/local-backend": "^1.0.449",
+    "@squidcloud/local-backend": "^1.0.451",
     "adm-zip": "^0.5.16",
     "copy-webpack-plugin": "^12.0.2",
     "decompress": "^4.2.1",