@shivaedev/sql 0.0.0 → 0.21.0

package/CHANGELOG.md

@@ -0,0 +1,269 @@
+# Changelog
+
+## 0.21.0 - 2026-10-25
+
+### Added
+
+- Versioned repositories accept composite keys so a consumer app can keep ownership and version predicates in one atomic write. `OptimisticConcurrencyError.reason` distinguishes `missing` from `stale` under the full key without exposing stored row data.
+- Versioned repositories with `conflictColumns` support `insertOrIgnore`, initializing the version to zero while leaving conflicting rows untouched. Unconditional upserts remain unavailable.
+- Unversioned repositories accept `update(input, { onMissing: "fail" })` to return a typed `NoSuchElementError` when no row matches a single-column or composite key. Updates still decode the returned row and announce changes only after commit; missing rows announce nothing. Calls without the option retain their missing-row defect, and versioned repositories retain their typed optimistic concurrency failures.
+
+## 0.20.0 - 2026-10-25
+
+### Added
+
+- `effect-sql` logs one lost warning per PostgreSQL listener outage and an info line after recovery, with `downtimeMs` since that warning and `streamCount` for the live streams resynchronized. Failed reconnect attempts log at debug. Initial successful startup logs neither outage line, and outage diagnostics omit database error causes and connection details.
+- `effect-contract`'s `makeLiveServer.resync` reports the number of open live streams it marked for reconciliation, excluding streams whose scopes have closed.
+
+### Breaking
+
+- Direct `postgresChanges` callers must supply `resync: Effect.Effect<number>` instead of `Effect.Effect<void>`. Pass `makeLiveServer.resync` unchanged, or return the number of open streams marked by your own stream owner.
+
+## 0.19.0 - 2026-10-25
+
+### Added
+
+- Repositories run typed grouped aggregates with model-derived group columns, numeric and boolean summaries, filters, ordering and limits.
+- effect-sql records the database release after successful migrations and coordinates worker drain with typed PostgreSQL heartbeat rows.
+- effect-pg-boss pauses fetching while the database belongs to another release, finishes active jobs, and resumes when its release owns the database again.
+- Platform migration options accept an optional `release` for deployment migration and worker readiness.
+- Generated workers step aside for a newer release and drain on SIGTERM, with queue expiry, stop timeout and Railway draining configured together.
+
+### Changed
+
+- `latestPerGroup` reads each pinned group through its index and stops after `limit` rows.
+
+## 0.18.0 - 2026-10-25
+
+### Added
+
+- effect-contract item reads refresh on their collection-wide `<collection>:*` key, with live hints naming each affected subscribed item.
+- `@shivaedev/effect-sql` exports `pendingPostgresMigrations` to read pending ledger migration IDs and names and schema component names and details.
+- `@shivaedev/platform` logs migration wait start, periodic progress, completion and timeout through Effect's logger with pending migration and component annotations. `migrations.progressInterval` controls progress logging independently of polling and defaults to 30 seconds.
+
+### Changed
+
+- `@shivaedev/create-app`'s starter worker uses the host's migration wait logs and keeps its job readiness line.
+
+### Breaking
+
+- effect-sql writes returning more than 1,000 rows across all chunks of a single call announce `<table>` and `<table>:*` instead of item keys. Code registering raw `<table>:<id>` Reactivity keys outside effect-contract must also register `<table>:*`.
+
+## 0.17.0 - 2026-10-25
+
+### Added
+
+- Repositories expose `count({ where })` with the same filters as `findMany`, returning a decoded number. Omit the filter to count every row; an empty table returns `0`.
+
+## 0.16.0 - 2026-10-25
+
+### Added
+
+- PostgreSQL repository upserts accept a typed `updateWhere` filter, including `excluded` column comparisons, and return inserted, updated or unchanged outcomes. Conditional `upsertMany` returns one outcome per input in a single transaction, preventing stale sync revisions from overwriting newer rows.
+
+## 0.15.0 - 2026-10-25
+
+### Added
+
+- Repository `findMany` and `select` filters accept typed `gt`, `gte`, `lt` and `lte` bounds, including UTC timestamps, and `like` text patterns, with runtime operand validation through model codecs.
+- Match several model fields together with `tupleIn(model, fields, tuples)` in `findMany`, `select` and unversioned `delete` filters. Tuples use each field's decoded type and codec, combine with other filters, and bind large lists as parameters. An empty tuple list matches nothing.
+
+## 0.14.0 - 2026-10-25
+
+### Added
+
+- Migration options accept schema components beside the numbered loader. Components apply after the ledger commits and report pending work through the same readiness check and host wait loop.
+- `pgBossSchema` registers pg-boss installation and upgrades as a schema component, reporting the schema's installed and required versions.
+
+### Changed
+
+- Generated apps migrate pg-boss through their migration list and start producers and workers with schema migration disabled.
+
+### Fixed
+
+- Migration-step controllers capture schema-component services when constructed, keeping subsequent migration calls free of external service requirements.
+
+## 0.13.1 - 2026-10-24
+
+### Changed
+
+- Require Effect and its companion packages at exactly 4.0.5. Generated applications use the same versions.
+
+## 0.13.0 - 2026-10-19
+
+### Added
+
+- Repositories without a version column accept `delete(where: FindManyFilter<Model>)` with model-typed equality and `{ in: [...] }` filters alongside existing primary-key deletes. List values use field codecs, empty lists delete nothing, and deleted row keys are announced only after commit.
+
+## 0.12.0 - 2026-10-19
+
+### Added
+
+- Repositories expose `latestPerGroup({ partitionBy, orderBy, limit, where })` to read up to N rows per group in one statement, with typed filters applied before ranking and Schema-decoded results. `LatestPerGroup` and the existing `OrderBy` type are exported from `repository.ts`; the ordered sort keys include the caller's stable tie-break column.
+- `findMany` accepts a nonempty `orderBy` list of `{ field, direction }` entries, applying each in order to break ties with independently chosen directions. The single-object form and model field validation remain supported.
+
+## 0.11.0 - 2026-10-19
+
+### Added
+
+- `findMany` and `select` accept model-typed `{ in: [...] }` filter entries alongside equality entries. Each list value uses its field codec, empty lists match no rows, and array field values retain equality semantics. The `FindManyFilter` type describes these query filters.
+
+## 0.10.0 - 2026-10-19
+
+### Added
+
+- Repositories expose `select`, `insertFromSelect` and `insertFromSelectOrIgnore` to copy filtered projections into mapped target columns with compile-time name and type checks, Schema-decoded returned rows and transaction rollback. `RepositorySelect`, `InsertFromSelect` and `SelectWrites` describe the new query and write shapes; `makeInsertFromSelect` and `makeConflictClause` build their native SQL fragments.
+
+## 0.9.0 - 2026-10-19
+
+### Added
+
+- `makeRepository` accepts `conflictWhere` alongside `conflictColumns` to target partial unique indexes for `insertOrIgnore`, `insertManyOrIgnore`, `upsert` and `upsertMany`. Predicates use the existing typed equality filter, encode decoded field values and bind parameters; unmatched indexes fail with native `SqlError`.
+- `repositoryFilter.ts` exports the shared `RepositoryFilter` type and `makeFilter` builder used by query and conflict predicates.
+
+## 0.8.1 - 2026-10-19
+
+### Fixed
+
+- Repository writes to a table whose composite key includes a `bigint` column no longer fail with "Do not know how to serialize a BigInt"; their item keys encode each `bigint` key value as its decimal string, the same way a single-column `bigint` key is encoded.
+
+## 0.8.0 - 2026-10-19
+
+### Added
+
+- `advisoryXactLock(key: bigint | string)` takes a PostgreSQL transaction-scoped advisory lock inside `transact`, with string keys hashed by `hashtextextended(key, 0)`. `AdvisoryLockOutsideTransaction` is the typed failure when no transaction is active. `migratePostgres` uses the same lock function.
+
+## 0.7.0 - 2026-10-18
+
+### Added
+
+- Repository insert, update, delete, conflict and batch writes record the table key and returned row item keys through the existing commit channel, including generated IDs and void writes. Transactions deduplicate keys and discard rolled-back writes.
+- PostgreSQL migration batches own the same commit boundary, so repository seed and upgrade writes announce after the batch commits.
+- Low-level composition exposes `repositoryChanges(sql, table, columns)`, `RepositoryChanges`, and `repositoryWrites(model, sql, options, changes)`.
+- `testing.ts` exports `withChangeCoverage(body)` and `UnannouncedWrites`; PostgreSQL transaction statistics catch tables written without a recorded table key. `transact.ts` exports `ChangeObserver` for observing that channel.
+
+### Breaking
+
+- Repository writes now open their own `transact` boundary. Use `transact` for an enclosing transaction instead of bare `sql.withTransaction`, and remove explicit invalidations for repository table/item keys. Keep explicit invalidations for derived keys. Standalone batch calls now roll back all chunks together. Direct callers of `makeInsertMany`, `makeConflictWrites` or `makeVersionedWrites` must supply `options.changes` from `repositoryChanges`, or use `makeRepository`.
+
+## 0.6.0 - 2026-10-18
+
+### Added
+
+- effect-sql exports `MIGRATIONS_DIRECTORY` and `MIGRATION_FILE_PATTERN` from `migrationConvention.ts`, and `migrationsFromDirectory(root)` to discover the app's sequentially numbered migration files with Effect's filesystem loader.
+- create-app ships the starter's discovered `src/server/migrations/` folder and validates its zero-padded sequential filenames when packing the template.
+- effect-sql exports `clientOptions(options, { snakeCase? })` and `SqlNameTransforms` from `clientOptions.ts`. New clients configured with this helper use Effect SQL's native camelCase-to-snake_case query names and snake_case-to-camelCase results by default. Pass `{ snakeCase: false }` to preserve native names, or supply native transform functions in the options.
+- Platform's app database and app host configuration accept native `transformQueryNames` and `transformResultNames`, so applications can use effect-sql's client options without replacing the host's database layer.
+
+### Changed
+
+- Newly generated applications configure snake_case SQL columns through effect-sql. The starter migrates existing note ownership and word-count columns while retaining camelCase model fields.
+
+## 0.5.2 - 2026-10-18
+
+### Changed
+
+- `migratePostgres` rejects loaded migration IDs at or below the latest applied ID that are missing from the ledger with a typed native `MigrationError` (`kind: "BadState"`) naming those IDs; a deployment that relied on silently skipping them now fails. Migrations run in ID order, including with a custom loader.
+
+## 0.5.1 - 2026-10-18
+
+### Fixed
+
+- Align published framework dependencies with the current releases.
+
+## 0.5.0 - 2026-10-17
+
+### Added
+
+- Unversioned repositories expose `insertMany(inputs)`. Repositories declaring `conflictColumns` also expose `insertManyOrIgnore(inputs)` and `upsertMany(inputs, { updateColumns })`, with model-derived insert inputs, decoded model arrays, bounded SQL chunks and caller-owned native transactions. Empty batches return an empty array without writing.
+- `assertPostgresMigrations({ loader, table? })` in `assertPostgresMigrations.ts` verifies required migration IDs and names in the native ledger without executing migrations or creating a ledger. Missing or pending migrations fail with native `MigrationError` (`kind: "BadState"`); later ledger entries are allowed for rolling deployments.
+
+## 0.4.0 - 2026-10-16
+
+### Added
+
+- `makeRepository` accepts a composite `idColumn` tuple; `findById` and `delete` accept the full key object, and updates match every key column through the model's codecs.
+- Unversioned repositories with declared `conflictColumns` expose `insertOrIgnore(input)` returning an optional decoded model and `upsert(input, { updateColumns })` returning the inserted or updated model. Inputs use the model's insert schema, selected update columns exclude primary and conflict keys, and writes participate in native transactions. PostgreSQL tests cover these paths.
+
+## 0.3.0 - 2026-10-13
+
+### Changed
+
+- A failed `COMMIT` inside `transact` fails with a typed `SqlError` mapped through `onSqlError` instead of a defect.
+
+### Breaking
+
+- Requires stable Effect 4.0.4 in place of 4.0.0-rc.112. Effect 4.0.4 moves the former `effect/unstable/*` modules to `effect/*` and renames constructors such as `Config.string` to `Config.String`. Install `@effect/sql-pg` 4.0.4 alongside it, whose native PostgreSQL client replaces `pg`.
+- `PostgresChangeClient.listen` returns a scoped `Queue` of notifications, matching `PgClient.listen` in `@effect/sql-pg` 4.0.4.
+- JSON and JSONB columns are not supported. A repository write of a plain object to one fails with `SqlError`; give structured data its own columns or table.
+- PostgreSQL `int8` values read as `bigint` (use `Schema.BigInt`), `date` values read as `YYYY-MM-DD` strings, and `timestamp without time zone` values are read and written as UTC wall time.
+
+## 0.2.1 - 2026-10-12
+
+### Added
+
+- Repositories accept an optional `versionColumn`: inserts initialize it to zero, updates match the expected version and increment it atomically, and deletes require the expected version. Stale or missing rows fail with typed `OptimisticConcurrencyError`; returned updated models carry the new version. PostgreSQL tests cover concurrent writers, versioned deletion and void writes. Unversioned repositories retain native CRUD behavior.
+- `postgresChanges` in `postgresChanges.ts` binds `transact` to PostgreSQL LISTEN/NOTIFY using the writing transaction's SQL client. Each process delivers committed string or finite-number invalidation keys into local Reactivity. Rollback sends no notification.
+- The scoped listener uses a heartbeat to detect silent connection loss, resyncs live streams before cleanup on loss and again on recovery, and retries with a fresh subscription. Each native listener finalizer is bounded by `heartbeatTimeout`, so a stalled UNLISTEN does not block connection release, retry or process scope shutdown. UTF-8 payloads are split below PostgreSQL's 8,000-byte NOTIFY limit; an oversized individual key or unsupported key rolls back the transaction.
+- `BeforeCommit` and `CommittedSink` in `transact.ts` expose the SQL channel's binding seams.
+
+### Changed
+
+- Give the package an agent north star, a model-to-query usage guide, and dedicated north-star and roadmap docs; publish `docs/` alongside the README while keeping agent instructions out of npm.
+- Build package JavaScript, declarations and source maps with TypeScript 7.
+
+## 0.2.0 - 2026-10-04
+
+### Changed
+
+- Breaking: no root entry and no module that re-exports another. `exports` maps one `"./*.ts"` pattern to every module (`src` under the `source` condition, `dist` otherwise), so you import the module that defines a name, and a bundler sees only the modules you use. Where each name now lives:
+  - `@shivaedev/effect-sql`: `@shivaedev/effect-sql/repository.ts` (`FindMany`, `makeRepository`), `@shivaedev/effect-sql/transact.ts` (`InvalidationKeys`, `TransactOptions`, `invalidateOnCommit`, `transact`), `@shivaedev/effect-sql/migrations.ts` (`PostgresMigrationOptions`, `migratePostgres`)
+- `makeRepository` and `FindMany` moved out of the deleted entry file into `repository.ts`.
+
+## 0.1.1 - 2026-10-04
+
+### Changed
+
+- Imports that leave their folder go through `#` aliases declared in the `imports` field of `package.json`: `#*.ts` resolves to `src` under the `source` condition and to `dist` otherwise, and `#test/*` names a test file. The published modules and declarations name the package's own files through these aliases.
+
+- Consolidate duplicate test cases around observable package behavior.
+
+- Validate packed consumers and executable bins through the shared workspace gate.
+
+- Build with the `@shivaedev/quality` tsconfig presets, which target ESNext and allow only erasable TypeScript syntax.
+
+- Type-check with TypeScript 7 only. TypeScript 6 still builds the package.
+
+- Lint and format with the `@shivaedev/quality` Biome preset through `quality lint` at the repository root, which replaces the package's `check` script.
+
+- Run tests through the `@shivaedev/quality` Vitest projects, which take a test's environment from its file name. Type tests are named `*.typecheck.test.ts`.
+
+- Keep `package.json` in sort-package-json key order, checked by `quality lint`.
+
+## 0.1.0 - 2026-09-26
+
+### Added
+
+- Add native Effect model repositories with schema-derived equality filters,
+  selected result decoding, ordering and limits.
+- Treat `undefined` filter values as unconstrained and fail with `SchemaError`
+  for field names outside the model.
+- Add `transact` and `invalidateOnCommit`, built on `@shivaedev/effect-changes`:
+  native transactions with mapped SQL errors and Reactivity invalidation only
+  after the outermost commit.
+- Keep one invalidation set per `SqlClient`: `invalidateOnCommit` marks the set
+  of its own `SqlClient`, a transaction on another database nested inside
+  `transact` announces its own commit, and a `transact` re-entered on a database
+  with an open outer transaction joins it as a savepoint.
+- Die when `invalidateOnCommit` runs after its transaction finished instead of
+  dropping the keys, and when `transact` or `invalidateOnCommit` runs inside a
+  native transaction that `transact` did not begin.
+- Log an invalidation that fails after `COMMIT`, for example a Reactivity
+  subscriber that throws, as an error and return the committed result, so
+  callers do not retry writes that already landed. The same applies to
+  `invalidateOnCommit` outside a transaction.
+- Announce the keys when a caller is interrupted while `COMMIT` is in flight and
+  the database committed.
+- Add `migratePostgres`: run Effect SQL migrations under a transaction-scoped
+  advisory lock with a required `lockTimeout`. An infinite `lockTimeout` becomes
+  PostgreSQL's `lock_timeout = 0` (no timeout).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShivaeDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.