graphile-search-plugin 1.1.1 → 3.1.0

package/README.md

@@ -16,44 +16,64 @@
   </a>
 </p>
 
-**`graphile-search-plugin`** enables `ts_rank` ordering and auto-generated full-text search helpers for all `tsvector` fields in PostGraphile schemas.
+**`graphile-search-plugin`** enables auto-generated full-text search condition fields for all `tsvector` columns in PostGraphile v5 schemas.
 
-## 🚀 Installation
+## Installation
 
 ```sh
 npm install graphile-search-plugin
 ```
 
-## ✨ Features
+## Features
 
-- Adds full-text search helpers for `tsvector` columns
-- Enables ordering via `ts_rank` on generated search fields
-- Works with PostGraphile append plugin pipeline
+- Adds full-text search condition fields for `tsvector` columns
+- Uses `websearch_to_tsquery` for natural search syntax
+- Automatic `ORDER BY ts_rank(column, tsquery) DESC` relevance ordering (matching V4 behavior)
+- Cursor-based pagination remains stable — PostGraphile re-appends unique key columns after the relevance sort
+- Works with PostGraphile v5 preset/plugin pipeline
 
-## 📦 Usage
+## Usage
 
-1. Append the new plugins!
-2. Query `search<YourTsvectorColumn>` in the `conditions` field
-3. Enjoy!
+### With Preset (Recommended)
 
-```js
+```typescript
+import { PgSearchPreset } from 'graphile-search-plugin';
 
-import PgSearchPlugin from 'graphile-search-plugin';
-
-app.use(
-  postgraphile(connectionStr, schemas, {
-    appendPlugins: [
-        PgSearchPlugin
-    ]
-  })
-);
+const preset = {
+  extends: [
+    // ... your other presets
+    PgSearchPreset({ pgSearchPrefix: 'fullText' }),
+  ],
+};
 ```
 
-## 🧪 Examples
+### With Plugin Directly
+
+```typescript
+import { PgSearchPlugin } from 'graphile-search-plugin';
 
-Look in the tests ;)
+const preset = {
+  plugins: [
+    PgSearchPlugin({ pgSearchPrefix: 'fullText' }),
+  ],
+};
+```
+
+### GraphQL Query
+
+```graphql
+query SearchGoals($search: String!) {
+  goals(condition: { fullTextTsv: $search }) {
+    nodes {
+      id
+      title
+      description
+    }
+  }
+}
+```
 
-## 🧪 Testing
+## Testing
 
 ```sh
 # requires a local Postgres available (defaults to postgres/password@localhost:5432)

package/esm/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PostGraphile v5 Search Plugin
+ *
+ * Provides full-text search capabilities for tsvector columns.
+ *
+ * @example
+ * ```typescript
+ * import { PgSearchPlugin, PgSearchPreset } from 'graphile-search-plugin';
+ *
+ * // Option 1: Use the preset (recommended)
+ * const preset = {
+ *   extends: [
+ *     PgSearchPreset({
+ *       pgSearchPrefix: 'fullText',
+ *     }),
+ *   ],
+ * };
+ *
+ * // Option 2: Use the plugin directly
+ * const plugin = PgSearchPlugin({ pgSearchPrefix: 'fullText' });
+ * ```
+ */
+export { PgSearchPlugin, createPgSearchPlugin } from './plugin';
+export { PgSearchPreset } from './preset';
+export { TsvectorCodecPlugin, TsvectorCodecPreset, createTsvectorCodecPlugin, } from './tsvector-codec';
+export type { PgSearchPluginOptions } from './types';

package/esm/index.js

@@ -1,57 +1,25 @@
-// plugins/PgSearchPlugin.ts
 /**
- * PgSearchPlugin - Generates search conditions for tsvector columns
+ * PostGraphile v5 Search Plugin
+ *
+ * Provides full-text search capabilities for tsvector columns.
+ *
+ * @example
+ * ```typescript
+ * import { PgSearchPlugin, PgSearchPreset } from 'graphile-search-plugin';
+ *
+ * // Option 1: Use the preset (recommended)
+ * const preset = {
+ *   extends: [
+ *     PgSearchPreset({
+ *       pgSearchPrefix: 'fullText',
+ *     }),
+ *   ],
+ * };
+ *
+ * // Option 2: Use the plugin directly
+ * const plugin = PgSearchPlugin({ pgSearchPrefix: 'fullText' });
+ * ```
  */
-const PgSearchPlugin = (builder, options = {}) => {
-    const { pgSearchPrefix = 'tsv' } = options;
-    builder.hook('GraphQLInputObjectType:fields', (fields, build, context) => {
-        const { inflection } = build;
-        const { scope: { isPgCondition, pgIntrospection: table }, fieldWithHooks } = context;
-        if (!isPgCondition || !table || table.kind !== 'class')
-            return fields;
-        const tsvs = table.attributes.filter((attr) => attr.type.name === 'tsvector');
-        if (!tsvs.length)
-            return fields;
-        return build.extend(fields, tsvs.reduce((memo, attr) => {
-            const fieldName = inflection.camelCase(`${pgSearchPrefix}_${attr.name}`);
-            memo[fieldName] = fieldWithHooks(fieldName, { type: build.graphql.GraphQLString }, {});
-            return memo;
-        }, {}));
-    });
-    builder.hook('GraphQLObjectType:fields:field:args', (args, build, context) => {
-        const { pgSql: sql, inflection } = build;
-        const { scope: { isPgFieldConnection, isPgFieldSimpleCollection, pgFieldIntrospection: procOrTable, pgFieldIntrospectionTable: tableIfProc, }, addArgDataGenerator, } = context;
-        const table = tableIfProc || procOrTable;
-        if ((!isPgFieldConnection && !isPgFieldSimpleCollection) ||
-            !table ||
-            table.kind !== 'class') {
-            return args;
-        }
-        const tsvs = table.attributes.filter((attr) => attr.type.name === 'tsvector');
-        if (!tsvs.length)
-            return args;
-        tsvs.forEach((tsv) => {
-            const conditionFieldName = inflection.camelCase(`${pgSearchPrefix}_${tsv.name}`);
-            addArgDataGenerator(function addSearchCondition({ condition }) {
-                if (!condition || !(conditionFieldName in condition))
-                    return {};
-                const value = condition[conditionFieldName];
-                if (value == null)
-                    return {};
-                return {
-                    pgQuery: (queryBuilder) => {
-                        const tsquery = sql.fragment `websearch_to_tsquery('english', ${sql.value(value)})`;
-                        const tableAlias = queryBuilder.getTableAlias();
-                        // WHERE condition
-                        queryBuilder.where(sql.fragment `${tableAlias}.${sql.identifier(tsv.name)} @@ ${tsquery}`);
-                        // Automatically add ordering by relevance (descending)
-                        queryBuilder.orderBy(sql.fragment `ts_rank(${tableAlias}.${sql.identifier(tsv.name)}, ${tsquery})`, false);
-                    },
-                };
-            });
-        });
-        return args;
-    }, [], ['PgConnectionArgOrderBy']);
-};
-export { PgSearchPlugin };
-export default PgSearchPlugin;
+export { PgSearchPlugin, createPgSearchPlugin } from './plugin';
+export { PgSearchPreset } from './preset';
+export { TsvectorCodecPlugin, TsvectorCodecPreset, createTsvectorCodecPlugin, } from './tsvector-codec';

package/esm/plugin.d.ts

@@ -0,0 +1,44 @@
+/**
+ * PostGraphile v5 Search Plugin
+ *
+ * Generates search condition fields for tsvector columns. When a search term
+ * is provided via the condition input, this plugin applies a
+ * `column @@ websearch_to_tsquery('english', $value)` WHERE clause and
+ * automatically orders results by `ts_rank` (descending) for relevance.
+ *
+ * Additionally provides:
+ * - `matches` filter operator for postgraphile-plugin-connection-filter
+ * - `fullTextRank` computed fields on output types (null when no search active)
+ * - `FULL_TEXT_RANK_ASC/DESC` orderBy enum values
+ *
+ * Uses the graphile-build hooks API to extend condition input types with
+ * search fields for each tsvector column found on a table's codec.
+ *
+ * ARCHITECTURE NOTE:
+ * Condition field apply functions run during a deferred phase (SQL generation)
+ * on a queryBuilder proxy — NOT on the real PgSelectStep. The rank field plan
+ * runs earlier, during Grafast's planning phase, on the real PgSelectStep.
+ *
+ * To bridge these two phases we use a module-level WeakMap keyed by the SQL
+ * alias object (shared between proxy and PgSelectStep via reference identity).
+ *
+ * The rank field plan creates a `lambda` step that reads the row tuple at a
+ * dynamically-determined index. The condition apply adds `ts_rank(...)` to
+ * the SQL SELECT list via `proxy.selectAndReturnIndex()` and stores the
+ * resulting index in the WeakMap slot. At execution time the lambda reads
+ * the rank value from that index.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+import type { PgSearchPluginOptions } from './types';
+/**
+ * Creates the search plugin with the given options.
+ */
+export declare function createPgSearchPlugin(options?: PgSearchPluginOptions): GraphileConfig.Plugin;
+/**
+ * Creates a PgSearchPlugin with the given options.
+ * This is the main entry point for using the plugin.
+ */
+export declare const PgSearchPlugin: typeof createPgSearchPlugin;
+export default PgSearchPlugin;

package/esm/plugin.js

@@ -0,0 +1,263 @@
+/**
+ * PostGraphile v5 Search Plugin
+ *
+ * Generates search condition fields for tsvector columns. When a search term
+ * is provided via the condition input, this plugin applies a
+ * `column @@ websearch_to_tsquery('english', $value)` WHERE clause and
+ * automatically orders results by `ts_rank` (descending) for relevance.
+ *
+ * Additionally provides:
+ * - `matches` filter operator for postgraphile-plugin-connection-filter
+ * - `fullTextRank` computed fields on output types (null when no search active)
+ * - `FULL_TEXT_RANK_ASC/DESC` orderBy enum values
+ *
+ * Uses the graphile-build hooks API to extend condition input types with
+ * search fields for each tsvector column found on a table's codec.
+ *
+ * ARCHITECTURE NOTE:
+ * Condition field apply functions run during a deferred phase (SQL generation)
+ * on a queryBuilder proxy — NOT on the real PgSelectStep. The rank field plan
+ * runs earlier, during Grafast's planning phase, on the real PgSelectStep.
+ *
+ * To bridge these two phases we use a module-level WeakMap keyed by the SQL
+ * alias object (shared between proxy and PgSelectStep via reference identity).
+ *
+ * The rank field plan creates a `lambda` step that reads the row tuple at a
+ * dynamically-determined index. The condition apply adds `ts_rank(...)` to
+ * the SQL SELECT list via `proxy.selectAndReturnIndex()` and stores the
+ * resulting index in the WeakMap slot. At execution time the lambda reads
+ * the rank value from that index.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import { TYPES } from '@dataplan/pg';
+const ftsRankSlots = new WeakMap();
+/**
+ * FinalizationRegistry for defensive cleanup of ftsRankSlots entries.
+ * WeakMap entries are already eligible for GC when keys are unreachable,
+ * but this provides explicit cleanup and a hook for debugging leaks.
+ */
+const ftsRankCleanup = new FinalizationRegistry((heldValue) => {
+    ftsRankSlots.delete(heldValue);
+});
+function isTsvectorCodec(codec) {
+    return (codec?.extensions?.pg?.schemaName === 'pg_catalog' &&
+        codec?.extensions?.pg?.name === 'tsvector');
+}
+/**
+ * Navigates from a PgSelectSingleStep up to the PgSelectStep.
+ * Uses duck-typing to avoid dependency on exact class names across rc versions.
+ */
+function getPgSelectStep($someStep) {
+    let $step = $someStep;
+    if ($step && typeof $step.getClassStep === 'function') {
+        $step = $step.getClassStep();
+    }
+    if ($step && typeof $step.orderBy === 'function' && $step.id !== undefined) {
+        return $step;
+    }
+    return null;
+}
+/**
+ * Creates the search plugin with the given options.
+ */
+export function createPgSearchPlugin(options = {}) {
+    const { pgSearchPrefix = 'tsv', fullTextScalarName = 'FullText', tsConfig = 'english' } = options;
+    return {
+        name: 'PgSearchPlugin',
+        version: '2.0.0',
+        description: 'Generates search conditions for tsvector columns in PostGraphile v5',
+        after: ['PgAttributesPlugin', 'PgConnectionArgFilterPlugin', 'PgConnectionArgFilterOperatorsPlugin', 'AddConnectionFilterOperatorPlugin'],
+        schema: {
+            hooks: {
+                init(_, build) {
+                    const { sql, graphql: { GraphQLString }, } = build;
+                    // Register the `matches` filter operator for the FullText scalar.
+                    // Requires postgraphile-plugin-connection-filter; skip if not loaded.
+                    const addConnectionFilterOperator = build
+                        .addConnectionFilterOperator;
+                    if (typeof addConnectionFilterOperator === 'function') {
+                        const TYPES = build.dataplanPg?.TYPES;
+                        addConnectionFilterOperator(fullTextScalarName, 'matches', {
+                            description: 'Performs a full text search on the field.',
+                            resolveType: () => GraphQLString,
+                            resolveInputCodec: TYPES ? () => TYPES.text : undefined,
+                            resolve(sqlIdentifier, sqlValue, _input, _$where, _details) {
+                                return sql `${sqlIdentifier} @@ websearch_to_tsquery(${sql.literal(tsConfig)}, ${sqlValue})`;
+                            },
+                        });
+                    }
+                    return _;
+                },
+                GraphQLObjectType_fields(fields, build, context) {
+                    const { sql, inflection, graphql: { GraphQLFloat }, grafast: { constant, lambda }, } = build;
+                    const { scope: { isPgClassType, pgCodec }, fieldWithHooks, } = context;
+                    if (!isPgClassType || !pgCodec?.attributes) {
+                        return fields;
+                    }
+                    let newFields = fields;
+                    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+                        if (!isTsvectorCodec(attribute.codec))
+                            continue;
+                        const baseFieldName = inflection.attribute({ codec: pgCodec, attributeName });
+                        const fieldName = inflection.camelCase(`${baseFieldName}-rank`);
+                        newFields = build.extend(newFields, {
+                            [fieldName]: fieldWithHooks({ fieldName }, () => ({
+                                description: `Full-text search ranking when filtered by \`${baseFieldName}\`. Returns null when no search condition is active.`,
+                                type: GraphQLFloat,
+                                plan($step) {
+                                    const $select = getPgSelectStep($step);
+                                    if (!$select)
+                                        return constant(null);
+                                    if (typeof $select.setInliningForbidden === 'function') {
+                                        $select.setInliningForbidden();
+                                    }
+                                    // Initialise the WeakMap slot for this query, keyed by the
+                                    // SQL alias (same object ref on PgSelectStep and the proxy).
+                                    const alias = $select.alias;
+                                    if (!ftsRankSlots.has(alias)) {
+                                        ftsRankSlots.set(alias, {
+                                            indices: Object.create(null),
+                                        });
+                                        ftsRankCleanup.register($select, alias);
+                                    }
+                                    // Return a lambda that reads the rank value from the result
+                                    // row at a dynamically-determined index. The index is set
+                                    // by the condition apply (deferred phase) via the proxy's
+                                    // selectAndReturnIndex, and stored in the WeakMap slot.
+                                    const capturedField = baseFieldName;
+                                    const capturedAlias = alias;
+                                    return lambda($step, (row) => {
+                                        if (row == null)
+                                            return null;
+                                        const slot = ftsRankSlots.get(capturedAlias);
+                                        if (!slot || slot.indices[capturedField] === undefined)
+                                            return null;
+                                        const rawValue = row[slot.indices[capturedField]];
+                                        return rawValue == null ? null : parseFloat(rawValue);
+                                    }, true);
+                                },
+                            })),
+                        }, `PgSearchPlugin adding rank field '${fieldName}' for '${attributeName}' on '${pgCodec.name}'`);
+                    }
+                    return newFields;
+                },
+                GraphQLEnumType_values(values, build, context) {
+                    const { sql, inflection, } = build;
+                    const { scope: { isPgRowSortEnum, pgCodec }, } = context;
+                    if (!isPgRowSortEnum || !pgCodec?.attributes) {
+                        return values;
+                    }
+                    let newValues = values;
+                    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+                        if (!isTsvectorCodec(attribute.codec))
+                            continue;
+                        const fieldName = inflection.attribute({ codec: pgCodec, attributeName });
+                        const metaKey = `fts_order_${fieldName}`;
+                        const makePlan = (direction) => (step) => {
+                            // The enum apply runs during the PLANNING phase on PgSelectStep.
+                            // Store the requested direction in PgSelectStep._meta so that
+                            // the condition apply (deferred phase) can read it via the
+                            // proxy's getMetaRaw and add the actual ORDER BY clause.
+                            if (typeof step.setMeta === 'function') {
+                                step.setMeta(metaKey, direction);
+                            }
+                        };
+                        const ascName = inflection.constantCase(`${attributeName}_rank_asc`);
+                        const descName = inflection.constantCase(`${attributeName}_rank_desc`);
+                        newValues = build.extend(newValues, {
+                            [ascName]: {
+                                extensions: {
+                                    grafast: {
+                                        apply: makePlan('ASC'),
+                                    },
+                                },
+                            },
+                            [descName]: {
+                                extensions: {
+                                    grafast: {
+                                        apply: makePlan('DESC'),
+                                    },
+                                },
+                            },
+                        }, `PgSearchPlugin adding rank orderBy for '${attributeName}' on '${pgCodec.name}'`);
+                    }
+                    return newValues;
+                },
+                GraphQLInputObjectType_fields(fields, build, context) {
+                    const { inflection, sql, graphql: { GraphQLString }, } = build;
+                    const { scope: { isPgCondition, pgCodec }, fieldWithHooks, } = context;
+                    if (!isPgCondition ||
+                        !pgCodec ||
+                        !pgCodec.attributes ||
+                        pgCodec.isAnonymous) {
+                        return fields;
+                    }
+                    const tsvectorAttributes = Object.entries(pgCodec.attributes).filter(([_name, attr]) => isTsvectorCodec(attr.codec));
+                    if (tsvectorAttributes.length === 0) {
+                        return fields;
+                    }
+                    let newFields = fields;
+                    for (const [attributeName] of tsvectorAttributes) {
+                        const fieldName = inflection.camelCase(`${pgSearchPrefix}_${attributeName}`);
+                        const baseFieldName = inflection.attribute({ codec: pgCodec, attributeName });
+                        newFields = build.extend(newFields, {
+                            [fieldName]: fieldWithHooks({
+                                fieldName,
+                                isPgConnectionConditionInputField: true,
+                            }, {
+                                description: build.wrapDescription(`Full-text search on the \`${attributeName}\` tsvector column using \`websearch_to_tsquery\`.`, 'field'),
+                                type: GraphQLString,
+                                apply: function plan($condition, val) {
+                                    if (val == null)
+                                        return;
+                                    const tsquery = sql `websearch_to_tsquery(${sql.literal(tsConfig)}, ${sql.value(val)})`;
+                                    const columnExpr = sql `${$condition.alias}.${sql.identifier(attributeName)}`;
+                                    // WHERE: column @@ tsquery
+                                    $condition.where(sql `${columnExpr} @@ ${tsquery}`);
+                                    // Add ts_rank to the SELECT list via the proxy's
+                                    // selectAndReturnIndex. This runs during the deferred
+                                    // SQL-generation phase, so the expression goes into
+                                    // info.selects (the live array used for SQL generation).
+                                    const $parent = $condition.dangerouslyGetParent();
+                                    if (typeof $parent.selectAndReturnIndex === 'function') {
+                                        const rankSql = sql `ts_rank(${columnExpr}, ${tsquery})`;
+                                        const wrappedRankSql = sql `${sql.parens(rankSql)}::text`;
+                                        const rankIndex = $parent.selectAndReturnIndex(wrappedRankSql);
+                                        // Store the index in the alias-keyed WeakMap slot so
+                                        // the rank field's lambda can read it at execute time.
+                                        const slot = ftsRankSlots.get($condition.alias);
+                                        if (slot) {
+                                            slot.indices[baseFieldName] = rankIndex;
+                                        }
+                                    }
+                                    // ORDER BY ts_rank: check if the user provided an
+                                    // explicit rank orderBy enum (stored in meta during
+                                    // planning). If so, use their direction. Otherwise add
+                                    // automatic DESC ordering for relevance.
+                                    const metaKey = `fts_order_${baseFieldName}`;
+                                    const explicitDir = typeof $parent.getMetaRaw === 'function'
+                                        ? $parent.getMetaRaw(metaKey)
+                                        : undefined;
+                                    const orderDirection = explicitDir ?? 'DESC';
+                                    $parent.orderBy({
+                                        fragment: sql `ts_rank(${columnExpr}, ${tsquery})`,
+                                        codec: TYPES.float4,
+                                        direction: orderDirection,
+                                    });
+                                },
+                            }),
+                        }, `PgSearchPlugin adding condition field '${fieldName}' for tsvector column '${attributeName}' on '${pgCodec.name}'`);
+                    }
+                    return newFields;
+                },
+            },
+        },
+    };
+}
+/**
+ * Creates a PgSearchPlugin with the given options.
+ * This is the main entry point for using the plugin.
+ */
+export const PgSearchPlugin = createPgSearchPlugin;
+export default PgSearchPlugin;

package/esm/preset.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PostGraphile v5 Search Preset
+ *
+ * Provides a convenient preset for including search support in PostGraphile.
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { PgSearchPluginOptions } from './types';
+/**
+ * Creates a preset that includes the search plugin with the given options.
+ *
+ * @example
+ * ```typescript
+ * import { PgSearchPreset } from 'graphile-search-plugin';
+ *
+ * const preset = {
+ *   extends: [
+ *     PgSearchPreset({
+ *       pgSearchPrefix: 'fullText',
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export declare function PgSearchPreset(options?: PgSearchPluginOptions): GraphileConfig.Preset;
+export default PgSearchPreset;

package/esm/preset.js

@@ -0,0 +1,29 @@
+/**
+ * PostGraphile v5 Search Preset
+ *
+ * Provides a convenient preset for including search support in PostGraphile.
+ */
+import { createPgSearchPlugin } from './plugin';
+import { createTsvectorCodecPlugin } from './tsvector-codec';
+/**
+ * Creates a preset that includes the search plugin with the given options.
+ *
+ * @example
+ * ```typescript
+ * import { PgSearchPreset } from 'graphile-search-plugin';
+ *
+ * const preset = {
+ *   extends: [
+ *     PgSearchPreset({
+ *       pgSearchPrefix: 'fullText',
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export function PgSearchPreset(options = {}) {
+    return {
+        plugins: [createTsvectorCodecPlugin(options), createPgSearchPlugin(options)],
+    };
+}
+export default PgSearchPreset;

package/esm/tsvector-codec.d.ts

@@ -0,0 +1,29 @@
+/**
+ * TsvectorCodecPlugin
+ *
+ * Teaches PostGraphile v5 how to handle PostgreSQL's tsvector and tsquery types.
+ * Without this, tsvector columns are invisible to the schema builder and the
+ * search plugin cannot generate condition fields.
+ *
+ * This plugin:
+ * 1. Creates codecs for tsvector/tsquery via gather.hooks.pgCodecs_findPgCodec
+ * 2. Registers a custom "FullText" scalar type for tsvector columns
+ * 3. Maps tsvector codec to the FullText scalar (isolating filter operators)
+ * 4. Maps tsquery codec to GraphQL String
+ * 5. Optionally hides tsvector columns from output types
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { PgSearchPluginOptions } from './types';
+/**
+ * Creates a TsvectorCodecPlugin with the given options.
+ *
+ * @param options - Plugin configuration
+ * @returns GraphileConfig.Plugin
+ */
+export declare function createTsvectorCodecPlugin(options?: PgSearchPluginOptions): GraphileConfig.Plugin;
+/**
+ * Default static instance using default options.
+ * Maps tsvector to the "FullText" scalar.
+ */
+export declare const TsvectorCodecPlugin: GraphileConfig.Plugin;
+export declare const TsvectorCodecPreset: GraphileConfig.Preset;