/**
 * Documentation for the deleteQuery operation
 */

/**
 * Returns documentation for the deleteQuery operation
 * @return {string} markdown documentation
 */
export function deleteQueryDocs(): string {
  return `
# DeleteQuery Operation

## General Description

The \`deleteQuery\` operation removes entities from the database based on complex query parameters, providing more flexibility than the standard delete operation.

## Detailed Description

This operation allows you to delete entities that match complex query criteria using the same query system as the query operation. It's particularly useful when you need to delete entities based on advanced filtering conditions, relationships, or complex logic that can't be easily expressed with the standard delete operation.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| queryParams | object | Yes | The query parameters object that defines what entities to delete. Same structure as used in the query operation. |
| token | string | No | Authentication token for your request. If not provided, the system will use the default API key from environment variables. |
| tenantCode | string | No | Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables. |

### QueryParams Object Structure

Same as the standard query operation. See the query operation documentation for details.

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "deletedCount": number  // Number of deleted entities
}
\`\`\`

### Error Response

\`\`\`json
{
    "success": false,
    "error": "Error message describing what went wrong"
}
\`\`\`

## Example Usage

### Basic DeleteQuery

\`\`\`typescript
const result = await deleteQuery({
  queryParams: {
    entDefName: "Order",
    query: [
      {
        propVal: {
          name: "status",
          value: "Cancelled"
        },
        function: "equals"
      },
      {
        propVal: {
          name: "createDate",
          value: "2023-01-01T00:00:00Z"
        },
        function: "smaller"
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(\`Deleted \${result.deletedCount} cancelled orders from 2022\`);
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Complex DeleteQuery with Nested Conditions

\`\`\`typescript
const result = await deleteQuery({
  queryParams: {
    entDefName: "Product",
    query: [
      {
        propVal: {
          name: "category",
          value: "Electronics"
        },
        function: "equals",
        relation: "AND",
        children: [
          {
            propVal: {
              name: "price",
              value: 100
            },
            function: "smaller",
            relation: "OR"
          },
          {
            propVal: {
              name: "inStock",
              value: false
            },
            function: "equals"
          }
        ]
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(\`Deleted \${result.deletedCount} electronic products that are either under $100 or out of stock\`);
}
\`\`\`

### DeleteQuery with Relationship Filtering

\`\`\`typescript
const result = await deleteQuery({
  queryParams: {
    entDefName: "Order",
    includes: [
      {
        propertyName: "customer",
        query: [
          {
            propVal: {
              name: "status",
              value: "Inactive"
            },
            function: "equals"
          }
        ]
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(\`Deleted \${result.deletedCount} orders from inactive customers\`);
}
\`\`\`

## Additional Information

- The deleteQuery operation is permanent and cannot be undone. Use it with caution.
- This operation supports all the query capabilities of the query operation, including complex filtering, nested conditions, and relationship traversal.
- The operation returns the number of affected rows (deleted entities).
- For performance reasons, consider using more specific filters when deleting large numbers of entities.
- Access permissions are enforced based on the provided token.
- For simple delete operations, use the standard delete operation instead.
- Depending on the entity definition, deleting entities may cascade to related entities or be prevented by referential integrity constraints.
- For very large deletions, consider breaking the operation into smaller batches to avoid timeouts or performance issues.
`;
}

/**
 * Returns a brief summary of the deleteQuery operation.
 * @return {string} A short description of the function.
 */
export function deleteQuerySummary(): string {
  return `
**Purpose**: Removes multiple entities based on complex query criteria.

**When to use**:
- Batch deleting records
- Conditional data removal
- Filtering entities for deletion
- Relationship-based cleanup

**Inputs**:
- queryParams: Object with entity definition and query filters
- token (optional)
- tenantCode (optional)

**Returns**: Count of deleted entities.

**Effects**: PERMANENT DATA REMOVAL - Cannot be undone.
`;
}

export default deleteQueryDocs;